apex-ruby 1.0.7 → 1.0.9

data/ext/apex_ext/apex_src/cli/main.c

@@ -18,6 +18,179 @@
 #include <sys/ioctl.h>
 #include <limits.h>
 
+static char *read_file(const char *filename, size_t *len);
+
+/**
+ * Tracks which apex_options fields were set explicitly from argv so that
+ * merged config/document metadata cannot override them after apex_apply_metadata_to_options.
+ */
+typedef struct apex_cli_option_mask {
+    bool mode;
+    bool output_format;
+    bool xhtml;
+    bool strict_xhtml;
+    bool theme_name;
+    bool enable_plugins;
+    bool enable_tables;
+    bool enable_footnotes;
+    bool enable_smart_typography;
+    bool enable_math;
+    bool enable_file_includes;
+    bool hardbreaks;
+    bool standalone;
+    bool embed_stylesheet;
+    bool document_title;
+    bool pretty;
+    bool critic;
+    bool id_format;
+    bool generate_header_ids;
+    bool header_anchors;
+    bool relaxed_tables;
+    bool per_cell_alignment;
+    bool caption_position;
+    bool code_highlighter;
+    bool code_highlight_theme;
+    bool code_line_numbers;
+    bool highlight_language_only;
+    bool allow_alpha_lists;
+    bool allow_mixed_list_markers;
+    bool unsafe;
+    bool enable_sup_sub;
+    bool enable_divs;
+    bool enable_definition_lists;
+    bool enable_spans;
+    bool enable_autolink;
+    bool enable_strikethrough;
+    bool obfuscate_emails;
+    bool enable_aria;
+    bool enable_wiki_links;
+    bool enable_emoji_autocorrect;
+    bool enable_widont;
+    bool code_is_poetry;
+    bool enable_markdown_in_html;
+    bool random_footnote_ids;
+    bool enable_hashtags;
+    bool style_hashtags;
+    bool proofreader;
+    bool hr_page_break;
+    bool title_from_h1;
+    bool page_break_before_footnotes;
+    bool wikilink_space;
+    bool wikilink_extension;
+    bool wikilink_sanitize;
+    bool enable_metadata_transforms;
+    bool embed_images;
+    bool enable_image_captions;
+    bool title_captions_only;
+    bool base_directory;
+    bool bibliography;
+    bool csl_file;
+    bool suppress_bibliography;
+    bool link_citations;
+    bool show_tooltips;
+    bool indices;
+    bool suppress_index;
+    bool stylesheet;
+} apex_cli_option_mask;
+
+static void apex_cli_restore_argv_options(apex_options *opts,
+                                          const apex_options *snap,
+                                          const apex_cli_option_mask *m) {
+    if (m->mode) opts->mode = snap->mode;
+    if (m->output_format) opts->output_format = snap->output_format;
+    if (m->xhtml) opts->xhtml = snap->xhtml;
+    if (m->strict_xhtml) opts->strict_xhtml = snap->strict_xhtml;
+    if (m->theme_name) opts->theme_name = snap->theme_name;
+    if (m->enable_plugins) opts->enable_plugins = snap->enable_plugins;
+    if (m->enable_tables) opts->enable_tables = snap->enable_tables;
+    if (m->enable_footnotes) opts->enable_footnotes = snap->enable_footnotes;
+    if (m->enable_smart_typography) opts->enable_smart_typography = snap->enable_smart_typography;
+    if (m->enable_math) opts->enable_math = snap->enable_math;
+    if (m->enable_file_includes) opts->enable_file_includes = snap->enable_file_includes;
+    if (m->hardbreaks) opts->hardbreaks = snap->hardbreaks;
+    if (m->standalone) opts->standalone = snap->standalone;
+    if (m->embed_stylesheet) opts->embed_stylesheet = snap->embed_stylesheet;
+    if (m->document_title) opts->document_title = snap->document_title;
+    if (m->pretty) opts->pretty = snap->pretty;
+    if (m->critic) {
+        opts->enable_critic_markup = snap->enable_critic_markup;
+        opts->critic_mode = snap->critic_mode;
+    }
+    if (m->id_format) opts->id_format = snap->id_format;
+    if (m->generate_header_ids) opts->generate_header_ids = snap->generate_header_ids;
+    if (m->header_anchors) opts->header_anchors = snap->header_anchors;
+    if (m->relaxed_tables) opts->relaxed_tables = snap->relaxed_tables;
+    if (m->per_cell_alignment) opts->per_cell_alignment = snap->per_cell_alignment;
+    if (m->caption_position) opts->caption_position = snap->caption_position;
+    if (m->code_highlighter) opts->code_highlighter = snap->code_highlighter;
+    if (m->code_highlight_theme) opts->code_highlight_theme = snap->code_highlight_theme;
+    if (m->code_line_numbers) opts->code_line_numbers = snap->code_line_numbers;
+    if (m->highlight_language_only) opts->highlight_language_only = snap->highlight_language_only;
+    if (m->allow_alpha_lists) opts->allow_alpha_lists = snap->allow_alpha_lists;
+    if (m->allow_mixed_list_markers) opts->allow_mixed_list_markers = snap->allow_mixed_list_markers;
+    if (m->unsafe) opts->unsafe = snap->unsafe;
+    if (m->enable_sup_sub) opts->enable_sup_sub = snap->enable_sup_sub;
+    if (m->enable_divs) opts->enable_divs = snap->enable_divs;
+    if (m->enable_definition_lists) opts->enable_definition_lists = snap->enable_definition_lists;
+    if (m->enable_spans) opts->enable_spans = snap->enable_spans;
+    if (m->enable_autolink) opts->enable_autolink = snap->enable_autolink;
+    if (m->enable_strikethrough) opts->enable_strikethrough = snap->enable_strikethrough;
+    if (m->obfuscate_emails) opts->obfuscate_emails = snap->obfuscate_emails;
+    if (m->enable_aria) opts->enable_aria = snap->enable_aria;
+    if (m->enable_wiki_links) opts->enable_wiki_links = snap->enable_wiki_links;
+    if (m->enable_emoji_autocorrect) opts->enable_emoji_autocorrect = snap->enable_emoji_autocorrect;
+    if (m->enable_widont) opts->enable_widont = snap->enable_widont;
+    if (m->code_is_poetry) {
+        opts->code_is_poetry = snap->code_is_poetry;
+        opts->highlight_language_only = snap->highlight_language_only;
+    }
+    if (m->enable_markdown_in_html) opts->enable_markdown_in_html = snap->enable_markdown_in_html;
+    if (m->random_footnote_ids) opts->random_footnote_ids = snap->random_footnote_ids;
+    if (m->enable_hashtags) opts->enable_hashtags = snap->enable_hashtags;
+    if (m->style_hashtags) opts->style_hashtags = snap->style_hashtags;
+    if (m->proofreader) {
+        opts->proofreader_mode = snap->proofreader_mode;
+        opts->enable_critic_markup = snap->enable_critic_markup;
+        opts->critic_mode = snap->critic_mode;
+    }
+    if (m->hr_page_break) opts->hr_page_break = snap->hr_page_break;
+    if (m->title_from_h1) opts->title_from_h1 = snap->title_from_h1;
+    if (m->page_break_before_footnotes) opts->page_break_before_footnotes = snap->page_break_before_footnotes;
+    if (m->wikilink_space) opts->wikilink_space = snap->wikilink_space;
+    if (m->wikilink_extension) opts->wikilink_extension = snap->wikilink_extension;
+    if (m->wikilink_sanitize) opts->wikilink_sanitize = snap->wikilink_sanitize;
+    if (m->enable_metadata_transforms) opts->enable_metadata_transforms = snap->enable_metadata_transforms;
+    if (m->embed_images) opts->embed_images = snap->embed_images;
+    if (m->enable_image_captions) opts->enable_image_captions = snap->enable_image_captions;
+    if (m->title_captions_only) {
+        opts->title_captions_only = snap->title_captions_only;
+        opts->enable_image_captions = snap->enable_image_captions;
+    }
+    if (m->base_directory) opts->base_directory = snap->base_directory;
+    if (m->bibliography) {
+        opts->bibliography_files = snap->bibliography_files;
+        opts->enable_citations = snap->enable_citations;
+    }
+    if (m->csl_file) {
+        opts->csl_file = snap->csl_file;
+        opts->enable_citations = snap->enable_citations;
+    }
+    if (m->suppress_bibliography) opts->suppress_bibliography = snap->suppress_bibliography;
+    if (m->link_citations) opts->link_citations = snap->link_citations;
+    if (m->show_tooltips) opts->show_tooltips = snap->show_tooltips;
+    if (m->indices) {
+        opts->enable_indices = snap->enable_indices;
+        opts->enable_mmark_index_syntax = snap->enable_mmark_index_syntax;
+        opts->enable_textindex_syntax = snap->enable_textindex_syntax;
+        opts->enable_leanpub_index_syntax = snap->enable_leanpub_index_syntax;
+    }
+    if (m->suppress_index) opts->suppress_index = snap->suppress_index;
+    if (m->stylesheet) {
+        opts->stylesheet_paths = snap->stylesheet_paths;
+        opts->stylesheet_count = snap->stylesheet_count;
+    }
+}
+
     /* Remote plugin directory helpers (from plugins_remote.c) */
 typedef struct apex_remote_plugin apex_remote_plugin;
 typedef struct apex_remote_plugin_list apex_remote_plugin_list;
@@ -479,6 +652,192 @@ static void cli_collect_installed_from_root(const char *root,
     closedir(d);
 }
 
+/**
+ * Merge document metadata from one or more files (later files override).
+ * Sets *out to merged metadata (may be NULL if no blocks found in any file).
+ * Returns 0 on success, non-zero if a file could not be read.
+ */
+static int apex_cli_merge_doc_metadata_from_files(apex_mode_t mode,
+                                                  char **paths,
+                                                  size_t n,
+                                                  apex_metadata_item **out) {
+    apex_metadata_item *acc = NULL;
+    *out = NULL;
+    for (size_t i = 0; i < n; i++) {
+        if (!paths || !paths[i]) continue;
+        size_t len = 0;
+        char *raw = read_file(paths[i], &len);
+        if (!raw) {
+            apex_free_metadata(acc);
+            return 1;
+        }
+        char *copy = malloc(len + 1);
+        if (!copy) {
+            free(raw);
+            apex_free_metadata(acc);
+            return 1;
+        }
+        memcpy(copy, raw, len + 1);
+        free(raw);
+        char *ptr = copy;
+        apex_metadata_item *chunk = apex_extract_metadata_for_mode(&ptr, mode);
+        free(copy);
+        if (!chunk) continue;
+        apex_metadata_item *merged = apex_merge_metadata(acc, chunk, NULL);
+        if (acc) apex_free_metadata(acc);
+        apex_free_metadata(chunk);
+        acc = merged;
+    }
+    *out = acc;
+    return 0;
+}
+
+/**
+ * Print version, merged config (global + project + --meta-file + --meta), and plugin resolution.
+ */
+static void apex_cli_print_info(FILE *out,
+                                const apex_options *options,
+                                bool plugins_cli_override,
+                                bool plugins_cli_value,
+                                const char *meta_file,
+                                apex_metadata_item *cmdline_metadata) {
+    fprintf(out, "version: %s\n\n", apex_version_string());
+
+    char *global_config_path = apex_cli_find_global_config();
+    char *project_config_path = apex_cli_find_project_config(options);
+
+    apex_metadata_item *global_config_meta = NULL;
+    apex_metadata_item *project_config_meta = NULL;
+    apex_metadata_item *explicit_file_meta = NULL;
+
+    if (global_config_path) {
+        global_config_meta = apex_load_metadata_from_file(global_config_path);
+    }
+    if (project_config_path) {
+        project_config_meta = apex_load_metadata_from_file(project_config_path);
+    }
+    if (meta_file) {
+        explicit_file_meta = apex_load_metadata_from_file(meta_file);
+    }
+
+    apex_metadata_item *merged_config = NULL;
+    if (global_config_meta || project_config_meta || explicit_file_meta || cmdline_metadata) {
+        merged_config = apex_merge_metadata(
+            global_config_meta,
+            project_config_meta,
+            explicit_file_meta,
+            cmdline_metadata,
+            NULL);
+    }
+
+    if (global_config_meta) apex_free_metadata(global_config_meta);
+    if (project_config_meta) apex_free_metadata(project_config_meta);
+    if (explicit_file_meta) apex_free_metadata(explicit_file_meta);
+    if (global_config_path) free(global_config_path);
+    if (project_config_path) free(project_config_path);
+
+    fprintf(out, "---\n");
+    if (merged_config) {
+        apex_metadata_fprint_yaml_mapping(out, merged_config);
+    }
+    fprintf(out, "---\n\n");
+
+    apex_options eff = *options;
+    if (merged_config) {
+        apex_apply_metadata_to_options(merged_config, &eff);
+    }
+    if (plugins_cli_override) {
+        eff.enable_plugins = plugins_cli_value;
+    }
+    apex_free_metadata(merged_config);
+
+    if (!eff.enable_plugins) {
+        fprintf(out, "plugins:\n  enabled: false\n");
+        return;
+    }
+
+    fprintf(out, "plugins:\n  enabled: true\n  ids:\n");
+
+    cli_installed_plugin *installed_head = NULL;
+    char **installed_ids = NULL;
+    size_t installed_count = 0;
+    size_t installed_cap = 0;
+
+    char cwd[1024];
+    cwd[0] = '\0';
+    if (getcwd(cwd, sizeof(cwd)) != NULL && cwd[0] != '\0') {
+        char cwd_plugins[1200];
+        snprintf(cwd_plugins, sizeof(cwd_plugins), "%s/.apex/plugins", cwd);
+        cli_collect_installed_from_root(cwd_plugins,
+                                        &installed_head,
+                                        &installed_ids,
+                                        &installed_count,
+                                        &installed_cap);
+    }
+
+    if (options->base_directory && options->base_directory[0] != '\0') {
+        char base_plugins[1200];
+        snprintf(base_plugins, sizeof(base_plugins), "%s/.apex/plugins", options->base_directory);
+        cli_collect_installed_from_root(base_plugins,
+                                        &installed_head,
+                                        &installed_ids,
+                                        &installed_count,
+                                        &installed_cap);
+    }
+
+    char *git_root = apex_cli_git_toplevel();
+    if (git_root && git_root[0] != '\0' && cwd[0] != '\0') {
+        size_t root_len = strlen(git_root);
+        if (strncmp(cwd, git_root, root_len) == 0 &&
+            (cwd[root_len] == '/' || cwd[root_len] == '\0')) {
+            char git_plugins[1200];
+            snprintf(git_plugins, sizeof(git_plugins), "%s/.apex/plugins", git_root);
+            cli_collect_installed_from_root(git_plugins,
+                                            &installed_head,
+                                            &installed_ids,
+                                            &installed_count,
+                                            &installed_cap);
+        }
+        free(git_root);
+    }
+
+    const char *xdg = getenv("XDG_CONFIG_HOME");
+    char root[1024];
+    root[0] = '\0';
+    if (xdg && *xdg) {
+        snprintf(root, sizeof(root), "%s/apex/plugins", xdg);
+    } else {
+        const char *home = getenv("HOME");
+        if (home && *home) {
+            snprintf(root, sizeof(root), "%s/.config/apex/plugins", home);
+        }
+    }
+    if (root[0] != '\0') {
+        cli_collect_installed_from_root(root,
+                                        &installed_head,
+                                        &installed_ids,
+                                        &installed_count,
+                                        &installed_cap);
+    }
+
+    if (installed_ids) {
+        for (size_t i = 0; i < installed_count; i++) {
+            free(installed_ids[i]);
+        }
+        free(installed_ids);
+    }
+
+    if (!installed_head) {
+        fprintf(out, "    # (none installed)\n");
+    } else {
+        for (cli_installed_plugin *p = installed_head; p; p = p->next) {
+            const char *pid = p->id ? p->id : "";
+            fprintf(out, "    - %s\n", pid);
+        }
+    }
+    cli_free_installed_plugins(installed_head);
+}
+
 /* Profiling helpers (same as in apex.c) */
 static double get_time_ms(void) {
     struct timeval tv;
@@ -631,6 +990,9 @@ static void print_usage(const char *program_name) {
     fprintf(stderr, "  --hardbreaks           Treat newlines as hard breaks\n");
     fprintf(stderr, "  --header-anchors        Generate <a> anchor tags instead of header IDs\n");
     fprintf(stderr, "  -h, --help             Show this help message\n");
+    fprintf(stderr, "  -i, --info             Show version, merged config (YAML), and plugin ids; to stdout without files, to stderr when processing files\n");
+    fprintf(stderr, "  --extract-meta         Print merged document metadata from input file(s) as YAML and exit\n");
+    fprintf(stderr, "  -e, --extract-meta-value KEY  Print one metadata value for KEY and exit (uses merged metadata from files, last wins)\n");
     fprintf(stderr, "  --id-format FORMAT      Header ID format: gfm (default), mmd, or kramdown\n");
     fprintf(stderr, "                          (modes auto-set format; use this to override in unified mode)\n");
     fprintf(stderr, "  --[no-]includes        Enable file inclusion (enabled by default in unified mode)\n");
@@ -652,7 +1014,7 @@ static void print_usage(const char *program_name) {
     fprintf(stderr, "  --mmd-merge            Merge files from one or more mmd_merge-style index files into a single Markdown stream\n");
     fprintf(stderr, "                         Index files list document parts line-by-line; indentation controls header level shifting.\n");
     fprintf(stderr, "  -m, --mode MODE        Processor mode: commonmark, gfm, mmd, kramdown, unified (default)\n");
-    fprintf(stderr, "  -t, --to FORMAT        Output format: html (default), json (before filters), json-filtered/ast-json/ast (after filters), markdown/md, mmd, commonmark/cmark, kramdown, gfm, terminal/cli, terminal256, man, man-html\n");
+    fprintf(stderr, "  -t, --to FORMAT        Output format: html (default), xhtml (alias for html + --xhtml), strict-xhtml (alias for html + --strict-xhtml), json (before filters), json-filtered/ast-json/ast (after filters), markdown/md, mmd, commonmark/cmark, kramdown, gfm, terminal/cli, terminal256, man, man-html\n");
     fprintf(stderr, "  --no-bibliography       Suppress bibliography output\n");
     fprintf(stderr, "  --no-footnotes         Disable footnote support\n");
     fprintf(stderr, "  --no-ids                Disable automatic header ID generation\n");
@@ -677,8 +1039,8 @@ static void print_usage(const char *program_name) {
     fprintf(stderr, "  --[no-]progress          Show progress indicator during processing (enabled by default for TTY)\n");
     fprintf(stderr, "  --plugins              Enable external/plugin processing\n");
     fprintf(stderr, "  --pretty               Pretty-print HTML with indentation and whitespace\n");
-    fprintf(stderr, "  --xhtml                HTML5 output with self-closing void tags (<br />, <meta ... />)\n");
-    fprintf(stderr, "  --strict-xhtml         Polyglot XHTML/XML for parsers (xmlns, application/xhtml+xml meta; implies --xhtml). Mutually exclusive with --xhtml.\n");
+    fprintf(stderr, "  --xhtml                HTML5 output with self-closing void tags (<br />, <meta ... />). Same as -t xhtml.\n");
+    fprintf(stderr, "  --strict-xhtml         Polyglot XHTML/XML for parsers (xmlns, application/xhtml+xml meta; implies --xhtml). Mutually exclusive with --xhtml. Same as -t strict-xhtml.\n");
     fprintf(stderr, "  --reject               Reject all Critic Markup changes (revert edits)\n");
     fprintf(stderr, "  --[no-]relaxed-tables  Enable or disable relaxed table parsing (no separator rows required)\n");
     fprintf(stderr, "  --[no-]per-cell-alignment  Enable or disable per-cell alignment markers (colons at start/end of cells, enabled by default in unified mode)\n");
@@ -708,6 +1070,8 @@ static void print_usage(const char *program_name) {
     fprintf(stderr, "  --[no-]wikilink-sanitize  Sanitize wiki link URLs (lowercase, remove apostrophes, etc.)\n");
     fprintf(stderr, "  --theme NAME            Terminal theme name for -t terminal/terminal256 (from ~/.config/apex/terminal/themes/NAME.theme)\n");
     fprintf(stderr, "  --width N               Hard-wrap terminal/terminal256 output at N visible columns\n");
+    fprintf(stderr, "  --no-terminal-images    Do not render local images via imgcat/chafa/viu/catimg on terminal output\n");
+    fprintf(stderr, "  --terminal-image-width N  Max width/cells for terminal image tools (default: 50)\n");
     fprintf(stderr, "  -p, --paginate          Page terminal/cli/terminal256 output through a pager (APEX_PAGER, then PAGER, then less -R)\n");
     fprintf(stderr, "\n");
     fprintf(stderr, "If no file is specified, reads from stdin.\n");
@@ -1522,10 +1886,15 @@ int main(int argc, char *argv[]) {
     init_progress();
 
     apex_options options = apex_options_default();
+    apex_options cli_options_snapshot;
+    apex_cli_option_mask cli_opt_mask = {0};
     bool plugins_cli_override = false;
     bool plugins_cli_value = false;
     bool list_plugins = false;
     bool list_themes = false;
+    bool cli_info = false;
+    bool cli_extract_meta = false;
+    const char *extract_meta_value_key = NULL;
     const char *install_plugin_id = NULL;
     const char *uninstall_plugin_id = NULL;
     bool list_filters = false;
@@ -1585,6 +1954,10 @@ int main(int argc, char *argv[]) {
     /* Pagination for terminal/terminal256 output */
     bool paginate_cli = false;
 
+    /* Terminal inline images: --no-terminal-images / --terminal-image-width N */
+    bool no_terminal_images_cli = false;
+    int terminal_image_width_cli = -1; /* -1 = use options default */
+
     /* Parse command-line arguments */
     for (int i = 1; i < argc; i++) {
         if (strcmp(argv[i], "-h") == 0 || strcmp(argv[i], "--help") == 0) {
@@ -1593,11 +1966,22 @@ int main(int argc, char *argv[]) {
         } else if (strcmp(argv[i], "-v") == 0 || strcmp(argv[i], "--version") == 0) {
             print_version();
             return 0;
+        } else if (strcmp(argv[i], "-i") == 0 || strcmp(argv[i], "--info") == 0) {
+            cli_info = true;
+        } else if (strcmp(argv[i], "--extract-meta") == 0) {
+            cli_extract_meta = true;
+        } else if (strcmp(argv[i], "-e") == 0 || strcmp(argv[i], "--extract-meta-value") == 0) {
+            if (++i >= argc) {
+                fprintf(stderr, "Error: --extract-meta-value requires a KEY argument\n");
+                return 1;
+            }
+            extract_meta_value_key = argv[i];
         } else if (strcmp(argv[i], "-m") == 0 || strcmp(argv[i], "--mode") == 0) {
             if (++i >= argc) {
                 fprintf(stderr, "Error: --mode requires an argument\n");
                 return 1;
             }
+            cli_opt_mask.mode = true;
             if (strcmp(argv[i], "commonmark") == 0) {
                 options = apex_options_for_mode(APEX_MODE_COMMONMARK);
             } else if (strcmp(argv[i], "gfm") == 0) {
@@ -1617,8 +2001,23 @@ int main(int argc, char *argv[]) {
                 fprintf(stderr, "Error: --to requires an argument\n");
                 return 1;
             }
+            cli_opt_mask.output_format = true;
             if (strcmp(argv[i], "html") == 0) {
                 options.output_format = APEX_OUTPUT_HTML;
+            } else if (strcmp(argv[i], "xhtml") == 0) {
+                /* Alias for -t html --xhtml */
+                cli_opt_mask.xhtml = true;
+                cli_opt_mask.strict_xhtml = true;
+                options.output_format = APEX_OUTPUT_HTML;
+                options.xhtml = true;
+                options.strict_xhtml = false;
+            } else if (strcmp(argv[i], "strict-xhtml") == 0) {
+                /* Alias for -t html --strict-xhtml */
+                cli_opt_mask.xhtml = true;
+                cli_opt_mask.strict_xhtml = true;
+                options.output_format = APEX_OUTPUT_HTML;
+                options.strict_xhtml = true;
+                options.xhtml = false;
             } else if (strcmp(argv[i], "json") == 0) {
                 options.output_format = APEX_OUTPUT_JSON;
             } else if (strcmp(argv[i], "json-filtered") == 0 || strcmp(argv[i], "ast-json") == 0 || strcmp(argv[i], "ast") == 0) {
@@ -1643,7 +2042,7 @@ int main(int argc, char *argv[]) {
                 options.output_format = APEX_OUTPUT_MAN_HTML;
             } else {
                 fprintf(stderr, "Error: Unknown output format '%s'\n", argv[i]);
-                fprintf(stderr, "Supported formats: html, json, json-filtered/ast-json/ast, markdown/md, mmd, commonmark/cmark, kramdown, gfm, terminal/cli, terminal256, man, man-html\n");
+                fprintf(stderr, "Supported formats: html, xhtml, strict-xhtml, json, json-filtered/ast-json/ast, markdown/md, mmd, commonmark/cmark, kramdown, gfm, terminal/cli, terminal256, man, man-html\n");
                 return 1;
             }
         } else if (strcmp(argv[i], "--theme") == 0) {
@@ -1651,6 +2050,7 @@ int main(int argc, char *argv[]) {
                 fprintf(stderr, "Error: --theme requires a name argument\n");
                 return 1;
             }
+            cli_opt_mask.theme_name = true;
             options.theme_name = argv[i];
         } else if (strcmp(argv[i], "--width") == 0) {
             if (++i >= argc) {
@@ -1663,6 +2063,18 @@ int main(int argc, char *argv[]) {
             }
         } else if (strcmp(argv[i], "-p") == 0 || strcmp(argv[i], "--paginate") == 0) {
             paginate_cli = true;
+        } else if (strcmp(argv[i], "--no-terminal-images") == 0) {
+            no_terminal_images_cli = true;
+        } else if (strcmp(argv[i], "--terminal-image-width") == 0) {
+            if (++i >= argc) {
+                fprintf(stderr, "Error: --terminal-image-width requires a positive integer\n");
+                return 1;
+            }
+            terminal_image_width_cli = atoi(argv[i]);
+            if (terminal_image_width_cli < 1) {
+                fprintf(stderr, "Error: --terminal-image-width must be at least 1\n");
+                return 1;
+            }
         } else if (strcmp(argv[i], "-o") == 0 || strcmp(argv[i], "--output") == 0) {
             if (++i >= argc) {
                 fprintf(stderr, "Error: --output requires an argument\n");
@@ -1670,10 +2082,12 @@ int main(int argc, char *argv[]) {
             }
             output_file = argv[i];
         } else if (strcmp(argv[i], "--plugins") == 0) {
+            cli_opt_mask.enable_plugins = true;
             options.enable_plugins = true;
             plugins_cli_override = true;
             plugins_cli_value = true;
         } else if (strcmp(argv[i], "--no-plugins") == 0) {
+            cli_opt_mask.enable_plugins = true;
             options.enable_plugins = false;
             plugins_cli_override = true;
             plugins_cli_value = false;
@@ -1757,26 +2171,36 @@ int main(int argc, char *argv[]) {
             }
             uninstall_plugin_id = argv[i];
         } else if (strcmp(argv[i], "--no-tables") == 0) {
+            cli_opt_mask.enable_tables = true;
             options.enable_tables = false;
         } else if (strcmp(argv[i], "--no-footnotes") == 0) {
+            cli_opt_mask.enable_footnotes = true;
             options.enable_footnotes = false;
         } else if (strcmp(argv[i], "--no-smart") == 0) {
+            cli_opt_mask.enable_smart_typography = true;
             options.enable_smart_typography = false;
         } else if (strcmp(argv[i], "--no-math") == 0) {
+            cli_opt_mask.enable_math = true;
             options.enable_math = false;
         } else if (strcmp(argv[i], "--includes") == 0) {
+            cli_opt_mask.enable_file_includes = true;
             options.enable_file_includes = true;
         } else if (strcmp(argv[i], "--no-includes") == 0) {
+            cli_opt_mask.enable_file_includes = true;
             options.enable_file_includes = false;
         } else if (strcmp(argv[i], "--hardbreaks") == 0) {
+            cli_opt_mask.hardbreaks = true;
             options.hardbreaks = true;
         } else if (strcmp(argv[i], "-s") == 0 || strcmp(argv[i], "--standalone") == 0) {
+            cli_opt_mask.standalone = true;
             options.standalone = true;
         } else if (strcmp(argv[i], "--css") == 0 || strcmp(argv[i], "--style") == 0) {
             if (++i >= argc) {
                 fprintf(stderr, "Error: %s requires an argument\n", argv[i-1]);
                 return 1;
             }
+            cli_opt_mask.standalone = true;
+            cli_opt_mask.stylesheet = true;
             options.standalone = true;  /* Imply standalone if CSS is specified */
 
             /* Parse comma-separated stylesheet paths */
@@ -1841,6 +2265,7 @@ int main(int argc, char *argv[]) {
                 }
             }
         } else if (strcmp(argv[i], "--embed-css") == 0) {
+            cli_opt_mask.embed_stylesheet = true;
             options.embed_stylesheet = true;
         } else if (strcmp(argv[i], "--script") == 0) {
             if (++i >= argc) {
@@ -1952,17 +2377,23 @@ int main(int argc, char *argv[]) {
                 fprintf(stderr, "Error: --title requires an argument\n");
                 return 1;
             }
+            cli_opt_mask.document_title = true;
             options.document_title = argv[i];
         } else if (strcmp(argv[i], "--pretty") == 0) {
+            cli_opt_mask.pretty = true;
             options.pretty = true;
         } else if (strcmp(argv[i], "--xhtml") == 0) {
+            cli_opt_mask.xhtml = true;
             options.xhtml = true;
         } else if (strcmp(argv[i], "--strict-xhtml") == 0) {
+            cli_opt_mask.strict_xhtml = true;
             options.strict_xhtml = true;
         } else if (strcmp(argv[i], "--accept") == 0) {
+            cli_opt_mask.critic = true;
             options.enable_critic_markup = true;
             options.critic_mode = 0;  /* CRITIC_ACCEPT */
         } else if (strcmp(argv[i], "--reject") == 0) {
+            cli_opt_mask.critic = true;
             options.enable_critic_markup = true;
             options.critic_mode = 1;  /* CRITIC_REJECT */
         } else if (strcmp(argv[i], "--id-format") == 0) {
@@ -1970,6 +2401,7 @@ int main(int argc, char *argv[]) {
                 fprintf(stderr, "Error: --id-format requires an argument (gfm, mmd, or kramdown)\n");
                 return 1;
             }
+            cli_opt_mask.id_format = true;
             if (strcmp(argv[i], "gfm") == 0) {
                 options.id_format = 0;  /* GFM format */
             } else if (strcmp(argv[i], "mmd") == 0) {
@@ -1981,22 +2413,29 @@ int main(int argc, char *argv[]) {
                 return 1;
             }
         } else if (strcmp(argv[i], "--no-ids") == 0) {
+            cli_opt_mask.generate_header_ids = true;
             options.generate_header_ids = false;
         } else if (strcmp(argv[i], "--header-anchors") == 0) {
+            cli_opt_mask.header_anchors = true;
             options.header_anchors = true;
         } else if (strcmp(argv[i], "--relaxed-tables") == 0) {
+            cli_opt_mask.relaxed_tables = true;
             options.relaxed_tables = true;
         } else if (strcmp(argv[i], "--no-relaxed-tables") == 0) {
+            cli_opt_mask.relaxed_tables = true;
             options.relaxed_tables = false;
         } else if (strcmp(argv[i], "--per-cell-alignment") == 0) {
+            cli_opt_mask.per_cell_alignment = true;
             options.per_cell_alignment = true;
         } else if (strcmp(argv[i], "--no-per-cell-alignment") == 0) {
+            cli_opt_mask.per_cell_alignment = true;
             options.per_cell_alignment = false;
         } else if (strcmp(argv[i], "--captions") == 0) {
             if (++i >= argc) {
                 fprintf(stderr, "Error: --captions requires an argument (above or below)\n");
                 return 1;
             }
+            cli_opt_mask.caption_position = true;
             if (strcmp(argv[i], "above") == 0) {
                 options.caption_position = 0;
             } else if (strcmp(argv[i], "below") == 0) {
@@ -2010,6 +2449,7 @@ int main(int argc, char *argv[]) {
                 fprintf(stderr, "Error: --code-highlight requires a tool name (pygments, skylighting, shiki, or abbreviations p, s, sh)\n");
                 return 1;
             }
+            cli_opt_mask.code_highlighter = true;
             /* Accept full names and abbreviations */
             if (strcmp(argv[i], "pygments") == 0 || strcmp(argv[i], "p") == 0 || strcmp(argv[i], "pyg") == 0) {
                 options.code_highlighter = "pygments";
@@ -2027,95 +2467,132 @@ int main(int argc, char *argv[]) {
                 fprintf(stderr, "Error: --code-highlight-theme requires a theme name\n");
                 return 1;
             }
+            cli_opt_mask.code_highlight_theme = true;
             options.code_highlight_theme = argv[i];
         } else if (strcmp(argv[i], "--code-line-numbers") == 0) {
+            cli_opt_mask.code_line_numbers = true;
             options.code_line_numbers = true;
         } else if (strcmp(argv[i], "--highlight-language-only") == 0) {
+            cli_opt_mask.highlight_language_only = true;
             options.highlight_language_only = true;
         } else if (strcmp(argv[i], "--alpha-lists") == 0) {
+            cli_opt_mask.allow_alpha_lists = true;
             options.allow_alpha_lists = true;
         } else if (strcmp(argv[i], "--no-alpha-lists") == 0) {
+            cli_opt_mask.allow_alpha_lists = true;
             options.allow_alpha_lists = false;
         } else if (strcmp(argv[i], "--mixed-lists") == 0) {
+            cli_opt_mask.allow_mixed_list_markers = true;
             options.allow_mixed_list_markers = true;
         } else if (strcmp(argv[i], "--no-mixed-lists") == 0) {
+            cli_opt_mask.allow_mixed_list_markers = true;
             options.allow_mixed_list_markers = false;
         } else if (strcmp(argv[i], "--unsafe") == 0) {
+            cli_opt_mask.unsafe = true;
             options.unsafe = true;
         } else if (strcmp(argv[i], "--no-unsafe") == 0) {
+            cli_opt_mask.unsafe = true;
             options.unsafe = false;
         } else if (strcmp(argv[i], "--sup-sub") == 0) {
+            cli_opt_mask.enable_sup_sub = true;
             options.enable_sup_sub = true;
         } else if (strcmp(argv[i], "--no-sup-sub") == 0) {
+            cli_opt_mask.enable_sup_sub = true;
             options.enable_sup_sub = false;
         } else if (strcmp(argv[i], "--divs") == 0) {
+            cli_opt_mask.enable_divs = true;
             options.enable_divs = true;
         } else if (strcmp(argv[i], "--no-divs") == 0) {
+            cli_opt_mask.enable_divs = true;
             options.enable_divs = false;
         } else if (strcmp(argv[i], "--one-line-definitions") == 0) {
+            cli_opt_mask.enable_definition_lists = true;
             options.enable_definition_lists = true;
         } else if (strcmp(argv[i], "--no-one-line-definitions") == 0) {
+            cli_opt_mask.enable_definition_lists = true;
             options.enable_definition_lists = false;
         } else if (strcmp(argv[i], "--spans") == 0) {
+            cli_opt_mask.enable_spans = true;
             options.enable_spans = true;
         } else if (strcmp(argv[i], "--no-spans") == 0) {
+            cli_opt_mask.enable_spans = true;
             options.enable_spans = false;
         } else if (strcmp(argv[i], "--autolink") == 0) {
+            cli_opt_mask.enable_autolink = true;
             options.enable_autolink = true;
         } else if (strcmp(argv[i], "--no-autolink") == 0) {
+            cli_opt_mask.enable_autolink = true;
             options.enable_autolink = false;
         } else if (strcmp(argv[i], "--strikethrough") == 0) {
+            cli_opt_mask.enable_strikethrough = true;
             options.enable_strikethrough = true;
         } else if (strcmp(argv[i], "--no-strikethrough") == 0) {
+            cli_opt_mask.enable_strikethrough = true;
             options.enable_strikethrough = false;
         } else if (strcmp(argv[i], "--obfuscate-emails") == 0) {
+            cli_opt_mask.obfuscate_emails = true;
             options.obfuscate_emails = true;
         } else if (strcmp(argv[i], "--progress") == 0) {
             progress_enabled = true;
         } else if (strcmp(argv[i], "--no-progress") == 0) {
             progress_enabled = false;
         } else if (strcmp(argv[i], "--aria") == 0) {
+            cli_opt_mask.enable_aria = true;
             options.enable_aria = true;
-        } else if (strcmp(argv[i], "--no-plugins") == 0) {
-            options.enable_plugins = false;
         } else if (strcmp(argv[i], "--wikilinks") == 0) {
+            cli_opt_mask.enable_wiki_links = true;
             options.enable_wiki_links = true;
         } else if (strcmp(argv[i], "--no-wikilinks") == 0) {
+            cli_opt_mask.enable_wiki_links = true;
             options.enable_wiki_links = false;
         } else if (strcmp(argv[i], "--emoji-autocorrect") == 0) {
+            cli_opt_mask.enable_emoji_autocorrect = true;
             options.enable_emoji_autocorrect = true;
         } else if (strcmp(argv[i], "--no-emoji-autocorrect") == 0) {
+            cli_opt_mask.enable_emoji_autocorrect = true;
             options.enable_emoji_autocorrect = false;
         } else if (strcmp(argv[i], "--widont") == 0) {
+            cli_opt_mask.enable_widont = true;
             options.enable_widont = true;
         } else if (strcmp(argv[i], "--code-is-poetry") == 0) {
+            cli_opt_mask.code_is_poetry = true;
             options.code_is_poetry = true;
             options.highlight_language_only = true;
         } else if (strcmp(argv[i], "--markdown-in-html") == 0) {
+            cli_opt_mask.enable_markdown_in_html = true;
             options.enable_markdown_in_html = true;
         } else if (strcmp(argv[i], "--no-markdown-in-html") == 0) {
+            cli_opt_mask.enable_markdown_in_html = true;
             options.enable_markdown_in_html = false;
         } else if (strcmp(argv[i], "--random-footnote-ids") == 0) {
+            cli_opt_mask.random_footnote_ids = true;
             options.random_footnote_ids = true;
         } else if (strcmp(argv[i], "--hashtags") == 0) {
+            cli_opt_mask.enable_hashtags = true;
             options.enable_hashtags = true;
         } else if (strcmp(argv[i], "--style-hashtags") == 0) {
+            cli_opt_mask.style_hashtags = true;
             options.style_hashtags = true;
         } else if (strcmp(argv[i], "--proofreader") == 0) {
+            cli_opt_mask.proofreader = true;
             options.proofreader_mode = true;
             options.enable_critic_markup = true;
             options.critic_mode = 2;  /* Ensure markup mode */
         } else if (strcmp(argv[i], "--hr-page-break") == 0) {
+            cli_opt_mask.hr_page_break = true;
             options.hr_page_break = true;
         } else if (strcmp(argv[i], "--title-from-h1") == 0) {
+            cli_opt_mask.title_from_h1 = true;
             options.title_from_h1 = true;
         } else if (strcmp(argv[i], "--page-break-before-footnotes") == 0) {
+            cli_opt_mask.page_break_before_footnotes = true;
             options.page_break_before_footnotes = true;
         } else if (strcmp(argv[i], "--wikilink-space") == 0) {
             if (++i >= argc) {
                 fprintf(stderr, "Error: --wikilink-space requires an argument (dash, none, underscore, or space)\n");
                 return 1;
             }
+            cli_opt_mask.wikilink_space = true;
             if (strcmp(argv[i], "dash") == 0) {
                 options.wikilink_space = 0;
             } else if (strcmp(argv[i], "none") == 0) {
@@ -2133,31 +2610,42 @@ int main(int argc, char *argv[]) {
                 fprintf(stderr, "Error: --wikilink-extension requires an argument\n");
                 return 1;
             }
+            cli_opt_mask.wikilink_extension = true;
             options.wikilink_extension = argv[i];
         } else if (strcmp(argv[i], "--wikilink-sanitize") == 0) {
+            cli_opt_mask.wikilink_sanitize = true;
             options.wikilink_sanitize = true;
         } else if (strcmp(argv[i], "--no-wikilink-sanitize") == 0) {
+            cli_opt_mask.wikilink_sanitize = true;
             options.wikilink_sanitize = false;
         } else if (strcmp(argv[i], "--transforms") == 0) {
+            cli_opt_mask.enable_metadata_transforms = true;
             options.enable_metadata_transforms = true;
         } else if (strcmp(argv[i], "--no-transforms") == 0) {
+            cli_opt_mask.enable_metadata_transforms = true;
             options.enable_metadata_transforms = false;
         } else if (strcmp(argv[i], "--embed-images") == 0) {
+            cli_opt_mask.embed_images = true;
             options.embed_images = true;
         } else if (strcmp(argv[i], "--image-captions") == 0) {
+            cli_opt_mask.enable_image_captions = true;
             options.enable_image_captions = true;
         } else if (strcmp(argv[i], "--no-image-captions") == 0) {
+            cli_opt_mask.enable_image_captions = true;
             options.enable_image_captions = false;
         } else if (strcmp(argv[i], "--title-captions-only") == 0) {
+            cli_opt_mask.title_captions_only = true;
             options.title_captions_only = true;
             options.enable_image_captions = true;  /* implied when title-captions-only is set */
         } else if (strcmp(argv[i], "--no-title-captions-only") == 0) {
+            cli_opt_mask.title_captions_only = true;
             options.title_captions_only = false;
         } else if (strcmp(argv[i], "--base-dir") == 0) {
             if (++i >= argc) {
                 fprintf(stderr, "Error: --base-dir requires an argument\n");
                 return 1;
             }
+            cli_opt_mask.base_directory = true;
             options.base_directory = argv[i];
         } else if (strcmp(argv[i], "--bibliography") == 0) {
             if (++i >= argc) {
@@ -2180,6 +2668,7 @@ int main(int argc, char *argv[]) {
                 }
                 bibliography_files = new_files;
             }
+            cli_opt_mask.bibliography = true;
             bibliography_files[bibliography_count++] = argv[i];
             options.enable_citations = true;  /* Enable citations when bibliography is provided */
         } else if (strcmp(argv[i], "--csl") == 0) {
@@ -2187,22 +2676,29 @@ int main(int argc, char *argv[]) {
                 fprintf(stderr, "Error: --csl requires an argument\n");
                 return 1;
             }
+            cli_opt_mask.csl_file = true;
             options.csl_file = argv[i];
             options.enable_citations = true;  /* Enable citations when CSL is provided */
         } else if (strcmp(argv[i], "--no-bibliography") == 0) {
+            cli_opt_mask.suppress_bibliography = true;
             options.suppress_bibliography = true;
         } else if (strcmp(argv[i], "--link-citations") == 0) {
+            cli_opt_mask.link_citations = true;
             options.link_citations = true;
         } else if (strcmp(argv[i], "--show-tooltips") == 0) {
+            cli_opt_mask.show_tooltips = true;
             options.show_tooltips = true;
         } else if (strcmp(argv[i], "--indices") == 0) {
+            cli_opt_mask.indices = true;
             options.enable_indices = true;
             options.enable_mmark_index_syntax = true;
             options.enable_textindex_syntax = true;
             options.enable_leanpub_index_syntax = true;
         } else if (strcmp(argv[i], "--no-indices") == 0) {
+            cli_opt_mask.indices = true;
             options.enable_indices = false;
         } else if (strcmp(argv[i], "--no-index") == 0) {
+            cli_opt_mask.suppress_index = true;
             options.suppress_index = true;
         } else if (strcmp(argv[i], "--meta-file") == 0) {
             if (++i >= argc) {
@@ -2293,12 +2789,74 @@ int main(int argc, char *argv[]) {
         return 1;
     }
 
+    if (cli_info && (cli_extract_meta || extract_meta_value_key)) {
+        fprintf(stderr, "Error: --info cannot be combined with --extract-meta or --extract-meta-value\n");
+        return 1;
+    }
+    if (cli_extract_meta && extract_meta_value_key) {
+        fprintf(stderr, "Error: --extract-meta cannot be combined with --extract-meta-value\n");
+        return 1;
+    }
+
     /* Handle theme listing before normal conversion */
     if (list_themes) {
         apex_cli_print_highlight_themes();
         return 0;
     }
 
+    /* Extract document metadata and exit (before plugin/network subcommands) */
+    if (cli_extract_meta || extract_meta_value_key) {
+        if (mmd_merge_mode) {
+            fprintf(stderr, "Error: --extract-meta/--extract-meta-value cannot be used with --mmd-merge\n");
+            return 1;
+        }
+        bool has_files = (input_file != NULL) || (combine_mode && combine_file_count > 0);
+        if (!has_files) {
+            fprintf(stderr, "Error: --extract-meta requires at least one input file\n");
+            return 1;
+        }
+
+        apex_metadata_item *docmeta = NULL;
+        int merge_rc;
+        if (combine_mode) {
+            merge_rc = apex_cli_merge_doc_metadata_from_files(options.mode, combine_files, combine_file_count, &docmeta);
+        } else {
+            char *one_path[1];
+            one_path[0] = (char *)input_file;
+            merge_rc = apex_cli_merge_doc_metadata_from_files(options.mode, one_path, 1, &docmeta);
+        }
+        if (merge_rc != 0) {
+            if (cmdline_metadata) apex_free_metadata(cmdline_metadata);
+            return 1;
+        }
+
+        if (cli_extract_meta) {
+            apex_metadata_fprint_yaml_document(stdout, docmeta);
+            if (docmeta) apex_free_metadata(docmeta);
+            if (cmdline_metadata) apex_free_metadata(cmdline_metadata);
+            return 0;
+        }
+
+        const char *val = apex_metadata_get(docmeta, extract_meta_value_key);
+        if (!val) {
+            fprintf(stderr, "Error: metadata key '%s' not found\n", extract_meta_value_key);
+            if (docmeta) apex_free_metadata(docmeta);
+            if (cmdline_metadata) apex_free_metadata(cmdline_metadata);
+            return 1;
+        }
+        printf("%s\n", val);
+        if (docmeta) apex_free_metadata(docmeta);
+        if (cmdline_metadata) apex_free_metadata(cmdline_metadata);
+        return 0;
+    }
+
+    /* --info with no input files: print and exit */
+    if (cli_info && !input_file && !combine_mode && !mmd_merge_mode) {
+        apex_cli_print_info(stdout, &options, plugins_cli_override, plugins_cli_value, meta_file, cmdline_metadata);
+        if (cmdline_metadata) apex_free_metadata(cmdline_metadata);
+        return 0;
+    }
+
     /* Handle plugin listing/installation/uninstallation commands before normal conversion */
     if (list_plugins || install_plugin_id || uninstall_plugin_id) {
         if ((install_plugin_id && uninstall_plugin_id) || (install_plugin_id && list_plugins && uninstall_plugin_id)) {
@@ -3094,6 +3652,10 @@ int main(int argc, char *argv[]) {
             return 1;
         }
 
+        if (cli_info) {
+            apex_cli_print_info(stderr, &options, plugins_cli_override, plugins_cli_value, meta_file, cmdline_metadata);
+        }
+
         int rc = 0;
         for (size_t i = 0; i < mmd_merge_file_count; i++) {
             const char *path = mmd_merge_files[i];
@@ -3121,6 +3683,10 @@ int main(int argc, char *argv[]) {
             }
         }
 
+        if (cli_info) {
+            apex_cli_print_info(stderr, &options, plugins_cli_override, plugins_cli_value, meta_file, cmdline_metadata);
+        }
+
         int rc = 0;
         bool needs_separator = false;
 
@@ -3177,6 +3743,10 @@ int main(int argc, char *argv[]) {
         }
     }
 
+    if (cli_info && input_file && !combine_mode && !mmd_merge_mode) {
+        apex_cli_print_info(stderr, &options, plugins_cli_override, plugins_cli_value, meta_file, cmdline_metadata);
+    }
+
     /* Set input_file_path for plugins (APEX_FILE_PATH) */
     if (input_file) {
         /* When a file is provided, use the original path (as passed in) */
@@ -3310,130 +3880,80 @@ int main(int argc, char *argv[]) {
     size_t enhanced_len = input_len;
 
     if (merged_metadata) {
-        /* Build YAML front matter from merged metadata */
-        size_t yaml_size = 512;
-        char *yaml_buf = malloc(yaml_size);
-        if (yaml_buf) {
-            size_t yaml_pos = 0;
-            yaml_buf[yaml_pos++] = '-';
-            yaml_buf[yaml_pos++] = '-';
-            yaml_buf[yaml_pos++] = '-';
-            yaml_buf[yaml_pos++] = '\n';
-
-            /* Use extracted metadata position if available */
-            bool has_existing_metadata = (doc_metadata_end > 0);
-            size_t metadata_start_pos = 0;
-            size_t metadata_end_pos = doc_metadata_end;
-
-            /* Add all merged metadata */
-            apex_metadata_item *item = merged_metadata;
-            while (item) {
-                /* Escape value if it contains special characters */
-                bool needs_quotes = strchr(item->value, ':') || strchr(item->value, '\n') ||
-                                    strchr(item->value, '"') || strchr(item->value, '\\');
-
-                size_t needed = strlen(item->key) + strlen(item->value) + (needs_quotes ? 4 : 0) + 10;
-                if (yaml_pos + needed >= yaml_size) {
-                    yaml_size = (yaml_pos + needed) * 2;
-                    char *new_buf = realloc(yaml_buf, yaml_size);
-                    if (!new_buf) {
-                        free(yaml_buf);
-                        yaml_buf = NULL;
-                        break;
-                    }
-                    yaml_buf = new_buf;
-                }
+        bool has_existing_metadata = (doc_metadata_end > 0);
+        size_t metadata_start_pos = 0;
+        size_t metadata_end_pos = doc_metadata_end;
+
+        char *yaml_buf = NULL;
+        size_t yaml_sz = 0;
+        FILE *ym = open_memstream(&yaml_buf, &yaml_sz);
+        if (ym) {
+            fprintf(ym, "---\n");
+            apex_metadata_fprint_yaml_mapping(ym, merged_metadata);
+            fprintf(ym, "---\n");
+            fclose(ym);
+        }
 
-                if (needs_quotes) {
-                    int written = snprintf(yaml_buf + yaml_pos, yaml_size - yaml_pos, "%s: \"%s\"\n", item->key, item->value);
-                    if (written > 0) yaml_pos += written;
-                } else {
-                    int written = snprintf(yaml_buf + yaml_pos, yaml_size - yaml_pos, "%s: %s\n", item->key, item->value);
-                    if (written > 0) yaml_pos += written;
-                }
-                item = item->next;
-            }
-
-            if (yaml_buf) {
-                /* Add closing --- */
-                yaml_buf[yaml_pos++] = '-';
-                yaml_buf[yaml_pos++] = '-';
-                yaml_buf[yaml_pos++] = '-';
-                yaml_buf[yaml_pos++] = '\n';
-                yaml_buf[yaml_pos] = '\0';
-
-                if (has_existing_metadata) {
-                    /* Replace existing metadata */
-                    size_t before_len = metadata_start_pos;
-                    size_t after_len = input_len - metadata_end_pos;
-                    enhanced_len = before_len + yaml_pos + after_len;
-                    enhanced_markdown = malloc(enhanced_len + 1);
-                    if (enhanced_markdown) {
-                        if (before_len > 0) {
-                            memcpy(enhanced_markdown, markdown, before_len);
-                        }
-                        memcpy(enhanced_markdown + before_len, yaml_buf, yaml_pos);
-                        if (after_len > 0) {
-                            memcpy(enhanced_markdown + before_len + yaml_pos, markdown + metadata_end_pos, after_len);
-                        }
-                        enhanced_markdown[enhanced_len] = '\0';
+        if (yaml_buf && yaml_sz > 0) {
+            size_t yaml_pos = yaml_sz;
+
+            if (has_existing_metadata) {
+                /* Replace existing metadata */
+                size_t before_len = metadata_start_pos;
+                size_t after_len = input_len - metadata_end_pos;
+                enhanced_len = before_len + yaml_pos + after_len;
+                enhanced_markdown = malloc(enhanced_len + 1);
+                if (enhanced_markdown) {
+                    if (before_len > 0) {
+                        memcpy(enhanced_markdown, markdown, before_len);
                     }
-                } else {
-                    /* Prepend metadata */
-                    enhanced_len = yaml_pos + input_len;
-                    enhanced_markdown = malloc(enhanced_len + 1);
-                    if (enhanced_markdown) {
-                        memcpy(enhanced_markdown, yaml_buf, yaml_pos);
-                        memcpy(enhanced_markdown + yaml_pos, markdown, input_len);
-                        enhanced_markdown[enhanced_len] = '\0';
+                    memcpy(enhanced_markdown + before_len, yaml_buf, yaml_pos);
+                    if (after_len > 0) {
+                        memcpy(enhanced_markdown + before_len + yaml_pos, markdown + metadata_end_pos, after_len);
                     }
+                    enhanced_markdown[enhanced_len] = '\0';
+                }
+            } else {
+                /* Prepend metadata */
+                enhanced_len = yaml_pos + input_len;
+                enhanced_markdown = malloc(enhanced_len + 1);
+                if (enhanced_markdown) {
+                    memcpy(enhanced_markdown, yaml_buf, yaml_pos);
+                    memcpy(enhanced_markdown + yaml_pos, markdown, input_len);
+                    enhanced_markdown[enhanced_len] = '\0';
                 }
-                free(yaml_buf);
             }
+            free(yaml_buf);
         }
     }
     PROFILE_END(metadata_yaml_build);
 
     /* Set bibliography files in options (NULL-terminated array) */
-    char **saved_bibliography_files = NULL;
     if (bibliography_count > 0) {
         bibliography_files = realloc(bibliography_files, (bibliography_count + 1) * sizeof(char*));
         if (bibliography_files) {
             bibliography_files[bibliography_count] = NULL;  /* NULL terminator */
             options.bibliography_files = bibliography_files;
-            /* Save reference in case metadata mode resets options */
-            saved_bibliography_files = bibliography_files;
         }
     }
 
     /* Set stylesheet files in options (NULL-terminated array) */
-    char **saved_stylesheet_files = NULL;
     if (stylesheet_count > 0) {
         stylesheet_files = realloc(stylesheet_files, (stylesheet_count + 1) * sizeof(char*));
         if (stylesheet_files) {
             stylesheet_files[stylesheet_count] = NULL;  /* NULL terminator */
             options.stylesheet_paths = (const char **)stylesheet_files;
             options.stylesheet_count = stylesheet_count;
-            /* Save reference in case metadata mode resets options */
-            saved_stylesheet_files = stylesheet_files;
         }
     }
 
     /* Apply metadata to options - allows per-document control of command-line options */
     /* Note: Bibliography file loading from metadata will be handled in citations extension */
-    apex_output_format_t saved_output_format = options.output_format;
     if (merged_metadata) {
+        /* Snapshot argv-resolved options after wiring bibliography/stylesheet; merged metadata must not override explicit CLI flags. */
+        cli_options_snapshot = options;
         apex_apply_metadata_to_options(merged_metadata, &options);
-        /* Restore explicit CLI choices that metadata mode reset */
-        options.output_format = saved_output_format;
-        if (saved_bibliography_files && !options.bibliography_files) {
-            options.bibliography_files = saved_bibliography_files;
-        }
-        /* Restore stylesheet files if they were lost (e.g., if mode was set in metadata) */
-        if (saved_stylesheet_files && !options.stylesheet_paths) {
-            options.stylesheet_paths = (const char **)saved_stylesheet_files;
-            options.stylesheet_count = stylesheet_count;
-        }
+        apex_cli_restore_argv_options(&options, &cli_options_snapshot, &cli_opt_mask);
     }
 
     /* Re-apply explicit CLI override for plugins so it wins over metadata. */
@@ -3698,6 +4218,13 @@ int main(int argc, char *argv[]) {
         options.enable_smart_typography = false;
     }
 
+    if (no_terminal_images_cli) {
+        options.terminal_inline_images = false;
+    }
+    if (terminal_image_width_cli > 0) {
+        options.terminal_image_width = terminal_image_width_cli;
+    }
+
     /* Convert to output (HTML, Markdown, terminal, etc.) */
     char *html = apex_markdown_to_html(final_markdown, final_len, &options);