apex-ruby 1.0.29 → 1.0.31

data/ext/apex_ext/apex_src/docs/superpowers/plans/2026-07-12-toc-output-format.md

@@ -1,745 +0,0 @@
-# TOC Output Format Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add `-t toc` that emits a Markdown unordered list of heading links, plus `--toc-min-max` defaults shared with HTML TOC markers.
-
-**Architecture:** Early-exit `APEX_OUTPUT_TOC` after AST prep (same point as markdown/json-filtered). Refactor `src/extensions/toc.c` to share heading collection/ID assignment between HTML marker TOC and a new Markdown TOC emitter. Option defaults (`toc_min`/`toc_max`, default 1,3) seed both paths; marker-specified ranges still override.
-
-**Tech Stack:** C (Apex + cmark-gfm), existing `tests/test_output.c` suite runner, man page / wiki docs.
-
-**Spec:** `docs/superpowers/specs/2026-07-12-toc-output-format-design.md`
-
----
-
-## File map
-
-| File | Responsibility |
-|------|----------------|
-| `include/apex/apex.h` | `APEX_OUTPUT_TOC`; `toc_min` / `toc_max` on `apex_options` |
-| `src/apex.c` | Defaults; early-exit for TOC; pass defaults into `apex_process_toc` |
-| `src/extensions/toc.h` | Public Markdown helper; update `apex_process_toc` signature |
-| `src/extensions/toc.c` | Prefer manual IDs; Markdown emitter; default min/max when marker omits range |
-| `cli/main.c` | `-t toc`, `--toc-min-max`, help, option mask |
-| `src/extensions/metadata.c` | `toc-min-max` metadata key |
-| `tests/test_output.c` | `-t toc` + default-depth HTML TOC tests |
-| `tests/test_metadata.c` | Metadata `toc-min-max` parsing |
-| `man/apex.1.md` (+ regenerate `man/apex.1`) | Document format + flag |
-| `apex.wiki/Command-Line-Options.md`, `Syntax.md`, `Header-IDs.md` as needed | User docs |
-
----
-
-### Task 1: Options + enum surface
-
-**Files:**
-- Modify: `include/apex/apex.h`
-- Modify: `src/apex.c` (`apex_options_default`, and any `apex_options_for_mode` copies that re-init options)
-
-- [ ] **Step 1: Add enum value and option fields**
-
-In `include/apex/apex.h`, extend the output format enum:
-
-```c
-    APEX_OUTPUT_MAN = 10,           /* roff (man page source) */
-    APEX_OUTPUT_MAN_HTML = 11,      /* styled HTML man page */
-    APEX_OUTPUT_TOC = 12            /* Markdown TOC list only */
-```
-
-Near the header ID fields on `apex_options` (after `id_format`), add:
-
-```c
-    /* TOC depth defaults (used by -t toc and by HTML TOC markers without an explicit range) */
-    int toc_min;  /* Inclusive min heading level (default 1) */
-    int toc_max;  /* Inclusive max heading level (default 3) */
-```
-
-- [ ] **Step 2: Initialize defaults in `apex_options_default`**
-
-In `src/apex.c` inside `apex_options_default()`, after `opts.id_format = 0;`:
-
-```c
-    opts.toc_min = 1;
-    opts.toc_max = 3;
-```
-
-If `apex_options_for_mode()` rebuilds options via `apex_options_default()`, no extra work. If any mode path zeroes the struct without going through default, set `toc_min`/`toc_max` there too.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add include/apex/apex.h src/apex.c
-git commit -m "Add APEX_OUTPUT_TOC and toc_min/toc_max options"
-```
-
----
-
-### Task 2: Prefer manual heading IDs in TOC collection
-
-**Files:**
-- Modify: `src/extensions/toc.c`
-- Test: `tests/test_output.c`
-
-- [ ] **Step 1: Write failing test for manual ID in HTML TOC**
-
-Append inside `test_toc()` in `tests/test_output.c` (before suite_end):
-
-```c
-    /* Manual {#id} must appear in TOC hrefs */
-    const char *manual_id_toc =
-        "# Custom {#my-custom}\n\n{{TOC}}\n\n## Other";
-    html = apex_markdown_to_html(manual_id_toc, strlen(manual_id_toc), &opts);
-    assert_contains(html, "href=\"#my-custom\"", "TOC uses manual heading ID");
-    apex_free_string(html);
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-```bash
-cd /Users/ttscoff/Desktop/Code/apex/build && make apex_test_runner -j4 && ./apex_test_runner toc 2>&1 | rg -i "manual|FAIL|passed|failed"
-```
-
-Expected: failure on "TOC uses manual heading ID" (current code always regenerates from text).
-
-- [ ] **Step 3: Assign IDs from `user_data` when present**
-
-In `src/extensions/toc.c`, replace the ID assignment loop in `apex_process_toc` (and share later with Markdown) with a helper:
-
-```c
-static char *heading_id_from_attrs_or_text(const char *attrs, const char *text,
-                                           apex_id_format_t id_format) {
-    if (attrs) {
-        const char *id_attr = strstr(attrs, "id=\"");
-        if (id_attr) {
-            const char *id_start = id_attr + 4;
-            const char *id_end = strchr(id_start, '"');
-            if (id_end && id_end > id_start) {
-                size_t id_len = (size_t)(id_end - id_start);
-                char *id = malloc(id_len + 1);
-                if (id) {
-                    memcpy(id, id_start, id_len);
-                    id[id_len] = '\0';
-                    return id;
-                }
-            }
-        }
-    }
-    return apex_generate_header_id(text, id_format);
-}
-```
-
-Update `collect_headers` to store attrs (or look them up again). Simplest: keep attrs on the node and, when assigning IDs, pass `cmark_node` — better: store `char *attrs_copy` is unnecessary if we assign IDs during collection:
-
-In `collect_headers`, after creating `item`:
-
-```c
-const char *attrs = (const char *)cmark_node_get_user_data(node);
-/* no_toc check already uses attrs */
-item->id = NULL; /* assigned in assign_header_ids */
-```
-
-Add:
-
-```c
-static void assign_header_ids(header_item *headers, cmark_node *document,
-                              int id_format) {
-    /* Walk headers list in document order; for each, find matching heading
-     * OR store attrs on header_item during collect. Prefer storing attrs: */
-}
-```
-
-Preferred approach — extend `header_item`:
-
-```c
-typedef struct header_item {
-    int level;
-    char *text;
-    char *id;
-    char *attrs; /* borrowed? NO — strdup user_data or extract id immediately */
-    struct header_item *next;
-} header_item;
-```
-
-Simplest reliable approach: extract ID during `collect_headers` once you know `id_format` — change signature to:
-
-```c
-static header_item *collect_headers(cmark_node *node, header_item **tail,
-                                    int id_format);
-```
-
-and inside, after `normalize_toc_text`:
-
-```c
-item->id = heading_id_from_attrs_or_text(attrs, item->text,
-                                         (apex_id_format_t)id_format);
-```
-
-Update `free_headers` (already frees `id`). Remove the separate ID loop in `apex_process_toc`.
-
-- [ ] **Step 4: Run test to verify it passes**
-
-```bash
-cd /Users/ttscoff/Desktop/Code/apex/build && make apex_test_runner -j4 && ./apex_test_runner toc 2>&1 | rg -i "manual|FAIL|Results"
-```
-
-Expected: "TOC uses manual heading ID" passes; suite overall green enough to proceed (note: Task 3 will change bare-marker max depth).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/extensions/toc.c tests/test_output.c
-git commit -m "Prefer manual heading IDs when building TOC links"
-```
-
----
-
-### Task 3: Thread default min/max into HTML TOC markers
-
-**Files:**
-- Modify: `src/extensions/toc.h`
-- Modify: `src/extensions/toc.c`
-- Modify: `src/apex.c` (call site)
-- Test: `tests/test_output.c`
-
-- [ ] **Step 1: Write failing tests for option defaults on bare markers**
-
-In `test_toc()`:
-
-```c
-    /* Bare {{TOC}} should use option defaults (1-3): exclude H4 */
-    const char *bare_default_depth =
-        "# H1\n\n{{TOC}}\n\n## H2\n\n### H3\n\n#### H4";
-    html = apex_markdown_to_html(bare_default_depth, strlen(bare_default_depth), &opts);
-    assert_contains(html, "href=\"#h1\"", "Bare TOC includes H1 by default");
-    assert_contains(html, "href=\"#h3\"", "Bare TOC includes H3 by default");
-    assert_not_contains(html, "href=\"#h4\"", "Bare TOC excludes H4 by default (max 3)");
-    apex_free_string(html);
-
-    /* --toc-min-max via options: 2,4 */
-    apex_options depth_opts = opts;
-    depth_opts.toc_min = 2;
-    depth_opts.toc_max = 4;
-    html = apex_markdown_to_html(bare_default_depth, strlen(bare_default_depth), &depth_opts);
-    assert_not_contains(html, "href=\"#h1\"", "toc_min=2 excludes H1");
-    assert_contains(html, "href=\"#h4\"", "toc_max=4 includes H4");
-    apex_free_string(html);
-
-    /* Marker override wins over options */
-    const char *override_toc =
-        "# H1\n\n{{TOC:1-6}}\n\n## H2\n\n### H3\n\n#### H4\n\n##### H5";
-    html = apex_markdown_to_html(override_toc, strlen(override_toc), &depth_opts);
-    assert_contains(html, "href=\"#h1\"", "Marker range overrides toc_min");
-    assert_contains(html, "href=\"#h5\"", "Marker range overrides toc_max");
-    apex_free_string(html);
-```
-
-- [ ] **Step 2: Run tests to verify failure on H4 exclusion**
-
-```bash
-cd /Users/ttscoff/Desktop/Code/apex/build && make apex_test_runner -j4 && ./apex_test_runner toc 2>&1 | rg -i "Bare TOC excludes|FAIL|Results"
-```
-
-Expected: "Bare TOC excludes H4 by default" fails (today bare marker uses max 6).
-
-- [ ] **Step 3: Update API and `parse_toc_marker`**
-
-`src/extensions/toc.h`:
-
-```c
-char *apex_process_toc(const char *html, cmark_node *document, int id_format,
-                       int default_min, int default_max);
-```
-
-In `toc.c`, change `parse_toc_marker` to accept defaults:
-
-```c
-static void parse_toc_marker(const char *marker, int *min_level, int *max_level,
-                             int default_min, int default_max) {
-    *min_level = default_min;
-    *max_level = default_max;
-    /* ... existing parsing that overwrites when marker specifies min/max ... */
-}
-```
-
-Clamp after parse:
-
-```c
-if (*min_level < 1) *min_level = 1;
-if (*max_level > 6) *max_level = 6;
-if (*min_level > *max_level) *max_level = *min_level;
-```
-
-Update `apex_process_toc` signature and call:
-
-```c
-parse_toc_marker(marker, &min_level, &max_level, default_min, default_max);
-```
-
-In `src/apex.c`:
-
-```c
-char *with_toc = apex_process_toc(html, document, options->id_format,
-                                  options->toc_min, options->toc_max);
-```
-
-- [ ] **Step 4: Run `toc` suite**
-
-```bash
-cd /Users/ttscoff/Desktop/Code/apex/build && make apex_test_runner -j4 && ./apex_test_runner toc
-```
-
-Expected: all TOC tests pass. If any older test assumed H4+ from bare `{{TOC}}`, update that test to use an explicit marker range.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/extensions/toc.h src/extensions/toc.c src/apex.c tests/test_output.c
-git commit -m "Use toc_min/toc_max defaults for HTML TOC markers without a range"
-```
-
----
-
-### Task 4: Markdown TOC emitter + `-t toc` early exit
-
-**Files:**
-- Modify: `src/extensions/toc.h`
-- Modify: `src/extensions/toc.c`
-- Modify: `src/apex.c`
-- Test: `tests/test_output.c`
-
-- [ ] **Step 1: Write failing `-t toc` tests**
-
-Add to `test_toc()`:
-
-```c
-    /* -t toc: Markdown list, default depth 1-3 */
-    apex_options toc_opts = apex_options_default();
-    toc_opts.output_format = APEX_OUTPUT_TOC;
-    const char *doc =
-        "# Introduction\n\n"
-        "## Getting Started\n\n"
-        "### Installation\n\n"
-        "#### Too Deep\n\n"
-        "## Configuration\n\n"
-        "# API\n"
-        "{: .no_toc}\n";
-    char *md = apex_markdown_to_html(doc, strlen(doc), &toc_opts);
-    assert_contains(md, "- [Introduction](#introduction)\n", "TOC md has H1");
-    assert_contains(md, "  - [Getting Started](#getting-started)\n", "TOC md indents H2");
-    assert_contains(md, "    - [Installation](#installation)\n", "TOC md indents H3");
-    assert_not_contains(md, "Too Deep", "TOC md excludes H4 by default");
-    assert_not_contains(md, "API", "TOC md excludes no_toc heading");
-    assert_not_contains(md, "<nav", "TOC md is not HTML");
-    apex_free_string(md);
-
-    toc_opts.toc_min = 2;
-    toc_opts.toc_max = 4;
-    md = apex_markdown_to_html(doc, strlen(doc), &toc_opts);
-    assert_not_contains(md, "Introduction", "toc-min-max excludes H1");
-    assert_contains(md, "Too Deep", "toc-min-max includes H4");
-    apex_free_string(md);
-
-    /* id-format mmd */
-    toc_opts = apex_options_default();
-    toc_opts.output_format = APEX_OUTPUT_TOC;
-    toc_opts.id_format = 1; /* MMD */
-    md = apex_markdown_to_html("# Hello World\n", 14, &toc_opts);
-    assert_contains(md, "- [Hello World](#HelloWorld)\n", "TOC md respects MMD id-format");
-    apex_free_string(md);
-
-    /* empty */
-    toc_opts = apex_options_default();
-    toc_opts.output_format = APEX_OUTPUT_TOC;
-    md = apex_markdown_to_html("No headings here.\n", 18, &toc_opts);
-    if (md && (md[0] == '\0' || strcmp(md, "\n") == 0)) {
-        test_result(true, "TOC md empty when no headings");
-    } else {
-        test_result(false, "TOC md empty when no headings");
-    }
-    apex_free_string(md);
-```
-
-Adjust the MMD id expectation if `apex_generate_header_id` for "Hello World" differs — run a quick HTML render with `--id-format mmd` if needed and match that slug.
-
-- [ ] **Step 2: Run tests — expect missing format / wrong output**
-
-```bash
-cd /Users/ttscoff/Desktop/Code/apex/build && make apex_test_runner -j4 && ./apex_test_runner toc 2>&1 | rg -i "TOC md|FAIL|Results"
-```
-
-Expected: failures (TOC still goes through HTML path or ignores `APEX_OUTPUT_TOC`).
-
-- [ ] **Step 3: Implement `apex_generate_toc_markdown`**
-
-`toc.h`:
-
-```c
-char *apex_generate_toc_markdown(cmark_node *document, int id_format,
-                                 int min_level, int max_level);
-```
-
-`toc.c` — mirror nesting logic of `generate_toc_html`, but emit Markdown:
-
-```c
-char *apex_generate_toc_markdown(cmark_node *document, int id_format,
-                                 int min_level, int max_level) {
-    if (!document) return strdup("");
-    if (min_level < 1) min_level = 1;
-    if (max_level > 6) max_level = 6;
-    if (min_level > max_level) max_level = min_level;
-
-    header_item *tail = NULL;
-    header_item *headers = collect_headers(document, &tail, id_format);
-    if (!headers) return strdup("");
-
-    size_t capacity = 4096;
-    char *out = malloc(capacity);
-    if (!out) {
-        free_headers(headers);
-        return strdup("");
-    }
-    char *write = out;
-    size_t remaining = capacity;
-
-    #define ENSURE(n) do { \
-        if ((size_t)(n) >= remaining) { \
-            size_t used = (size_t)(write - out); \
-            capacity = used + (size_t)(n) + 1024; \
-            char *nbuf = realloc(out, capacity); \
-            if (!nbuf) { free(out); free_headers(headers); return strdup(""); } \
-            out = nbuf; write = out + used; remaining = capacity - used; \
-        } \
-    } while (0)
-
-    #define APPEND(str) do { \
-        size_t len = strlen(str); \
-        ENSURE(len + 1); \
-        memcpy(write, str, len); \
-        write += len; \
-        remaining -= len; \
-    } while (0)
-
-    for (header_item *h = headers; h; h = h->next) {
-        if (h->level < min_level || h->level > max_level) continue;
-        int depth = h->level - min_level; /* 0 = flush */
-        ENSURE((size_t)depth * 2 + strlen(h->text) + strlen(h->id) + 16);
-        for (int i = 0; i < depth; i++) APPEND("  ");
-        APPEND("- [");
-        APPEND(h->text);
-        APPEND("](#");
-        APPEND(h->id);
-        APPEND(")\n");
-    }
-
-    #undef APPEND
-    #undef ENSURE
-
-    *write = '\0';
-    free_headers(headers);
-    return out;
-}
-```
-
-- [ ] **Step 4: Early-exit in `apex_markdown_to_html`**
-
-In `src/apex.c`, immediately after the JSON_FILTERED early return (before Markdown dialects), add:
-
-```c
-    if (options->output_format == APEX_OUTPUT_TOC) {
-        char *toc_md = apex_generate_toc_markdown(document, options->id_format,
-                                                  options->toc_min, options->toc_max);
-        return toc_md ? toc_md : strdup("");
-    }
-```
-
-Include `toc.h` if not already included at the top of `apex.c`.
-
-- [ ] **Step 5: Run tests**
-
-```bash
-cd /Users/ttscoff/Desktop/Code/apex/build && make apex_test_runner -j4 && ./apex_test_runner toc
-```
-
-Expected: all pass. Fix MMD slug assertion if the actual slug differs.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/extensions/toc.h src/extensions/toc.c src/apex.c tests/test_output.c
-git commit -m "Add -t toc Markdown TOC output format"
-```
-
----
-
-### Task 5: CLI `--to toc` and `--toc-min-max`
-
-**Files:**
-- Modify: `cli/main.c`
-
-- [ ] **Step 1: Add option mask fields**
-
-In `apex_cli_option_mask`:
-
-```c
-    bool toc_min_max;
-```
-
-In `apex_apply_cli_option_mask` (or equivalent merge helper), copy when masked:
-
-```c
-    if (m->toc_min_max) {
-        opts->toc_min = snap->toc_min;
-        opts->toc_max = snap->toc_max;
-    }
-```
-
-- [ ] **Step 2: Parse `-t toc` and `--toc-min-max`**
-
-In the `-t` / `--to` branch, after `man-html`:
-
-```c
-            } else if (strcmp(format, "toc") == 0) {
-                options.output_format = APEX_OUTPUT_TOC;
-```
-
-Add flag parsing near `--id-format`:
-
-```c
-        } else if (strncmp(argv[i], "--toc-min-max=", 14) == 0 ||
-                   strcmp(argv[i], "--toc-min-max") == 0) {
-            const char *val = NULL;
-            if (strncmp(argv[i], "--toc-min-max=", 14) == 0) {
-                val = argv[i] + 14;
-            } else {
-                if (i + 1 >= argc) {
-                    fprintf(stderr, "Error: --toc-min-max requires MIN,MAX (e.g. 1,3)\n");
-                    return 1;
-                }
-                val = argv[++i];
-            }
-            int min = 0, max = 0;
-            if (sscanf(val, "%d,%d", &min, &max) != 2 ||
-                min < 1 || max > 6 || min > max) {
-                fprintf(stderr, "Error: --toc-min-max must be MIN,MAX with 1 <= MIN <= MAX <= 6\n");
-                return 1;
-            }
-            cli_opt_mask.toc_min_max = true;
-            options.toc_min = min;
-            options.toc_max = max;
-```
-
-- [ ] **Step 3: Help text**
-
-In `print_usage` / help:
-
-- Add `toc` to the `-t` formats list.
-- Add:
-
-```c
-    fprintf(stderr, "  --toc-min-max MIN,MAX  TOC heading depth range (default: 1,3); also seeds HTML TOC markers without an explicit range\n");
-```
-
-- [ ] **Step 4: Manual CLI smoke check**
-
-```bash
-cd /Users/ttscoff/Desktop/Code/apex/build && make apex -j4
-./apex -t toc --toc-min-max=2,4 <<'MD'
-# A
-## B
-### C
-#### D
-MD
-```
-
-Expected:
-
-```markdown
-- [B](#b)
-  - [C](#c)
-    - [D](#d)
-```
-
-Invalid flag:
-
-```bash
-./apex -t toc --toc-min-max=0,9 </dev/null; echo exit:$?
-```
-
-Expected: non-zero exit and error message.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add cli/main.c
-git commit -m "Add CLI -t toc and --toc-min-max"
-```
-
----
-
-### Task 6: Metadata `toc-min-max`
-
-**Files:**
-- Modify: `src/extensions/metadata.c`
-- Test: `tests/test_metadata.c` (suite that covers option keys — `test_metadata_control_options` or nearest)
-
-- [ ] **Step 1: Write failing metadata test**
-
-Follow existing `id-format` metadata tests in `tests/test_metadata.c`:
-
-```c
-    opts = apex_options_default();
-    /* build metadata list with key toc-min-max value 2,4 — same pattern as id-format test */
-    apex_apply_metadata_to_options(metadata, &opts); /* use actual helper name from nearby tests */
-    assert_option_bool(opts.toc_min == 2, true, "toc-min-max sets toc_min");
-    assert_option_bool(opts.toc_max == 4, true, "toc-min-max sets toc_max");
-```
-
-Read the surrounding `id-format` test and mirror its metadata list construction exactly.
-
-- [ ] **Step 2: Run test — expect fail**
-
-```bash
-cd /Users/ttscoff/Desktop/Code/apex/build && make apex_test_runner -j4 && ./apex_test_runner metadata_control_options 2>&1 | rg -i "toc-min|FAIL|Results"
-```
-
-(If the suite name differs, use the suite that contains the id-format metadata assertions.)
-
-- [ ] **Step 3: Parse in `metadata.c`**
-
-Near the `id-format` branch:
-
-```c
-        } else if (strcasecmp(key, "toc-min-max") == 0 || strcasecmp(key, "toc_min_max") == 0) {
-            int min = 0, max = 0;
-            if (sscanf(value, "%d,%d", &min, &max) == 2 &&
-                min >= 1 && max <= 6 && min <= max) {
-                options->toc_min = min;
-                options->toc_max = max;
-            }
-```
-
-Ignore invalid values silently (match how other metadata keys behave) unless nearby keys error loudly — stay consistent.
-
-- [ ] **Step 4: Run metadata + toc suites**
-
-```bash
-cd /Users/ttscoff/Desktop/Code/apex/build && make apex_test_runner -j4 && ./apex_test_runner toc && ./apex_test_runner metadata_control_options
-```
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/extensions/metadata.c tests/test_metadata.c
-git commit -m "Support toc-min-max metadata for TOC depth defaults"
-```
-
----
-
-### Task 7: Documentation
-
-**Files:**
-- Modify: `man/apex.1.md` (then `make man`)
-- Modify: `/Users/ttscoff/Desktop/Code/apex.wiki/Command-Line-Options.md`
-- Modify: `/Users/ttscoff/Desktop/Code/apex.wiki/Syntax.md` (TOC section)
-- Optionally: `/Users/ttscoff/Desktop/Code/apex.wiki/Header-IDs.md` (note `-t toc` uses same IDs)
-
-- [ ] **Step 1: Man page**
-
-Under `-t` / `--to` list, add:
-
-```markdown
-- **toc** - Markdown unordered list of heading links only (default depth `#`–`###`)
-```
-
-Add flag section:
-
-```markdown
-**--toc-min-max** *MIN,MAX*
-: Inclusive heading depth range for **--to toc** and for HTML TOC markers that do not specify their own range. Default **1,3**. Marker syntax such as `{{TOC:2-5}}` still overrides. Values must satisfy `1 <= MIN <= MAX <= 6`.
-```
-
-Regenerate:
-
-```bash
-cd /Users/ttscoff/Desktop/Code/apex && make man
-```
-
-- [ ] **Step 2: Wiki**
-
-In `Command-Line-Options.md`, document `-t toc` and `--toc-min-max` near other output/format flags.
-
-In `Syntax.md` TOC section, note:
-
-- Bare `{{TOC}}` / `<!--TOC-->` / `{:toc}` now default to levels 1–3 (or `--toc-min-max` / `toc-min-max` metadata).
-- `-t toc` extracts a Markdown TOC without markers.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add man/apex.1.md man/apex.1
-# wiki is a separate repo:
-cd /Users/ttscoff/Desktop/Code/apex.wiki && git add Command-Line-Options.md Syntax.md Header-IDs.md && git status
-```
-
-Commit apex and wiki separately with clear messages. Do not push unless asked.
-
----
-
-### Task 8: Final verification
-
-- [ ] **Step 1: Full relevant test pass**
-
-```bash
-cd /Users/ttscoff/Desktop/Code/apex/build && make -j4 && ./apex_test_runner toc && ./apex_test_runner header_ids && ./apex_test_runner metadata_control_options
-```
-
-- [ ] **Step 2: End-to-end smoke**
-
-```bash
-./apex -t toc <<'MD'
-# Intro
-## Details
-### Deep
-#### Deeper
-MD
-./apex -t toc --toc-min-max=1,6 <<'MD'
-# Intro
-## Details
-### Deep
-#### Deeper
-MD
-./apex -t html <<'MD'
-# Intro
-{{TOC}}
-## Details
-### Deep
-#### Deeper
-MD
-```
-
-Confirm Markdown TOC and HTML bare TOC both stop at `###` by default; `--toc-min-max=1,6` includes `####`.
-
-- [ ] **Step 3: Update `commit_message.txt` only if the user asks for a changelog commit message**
-
----
-
-## Spec coverage checklist
-
-| Spec requirement | Task |
-|------------------|------|
-| `-t toc` Markdown list `[Title](#id)` | 4, 5 |
-| Default depth 1–3 | 1, 3, 4 |
-| `--toc-min-max` | 5 |
-| Flag seeds HTML markers; marker overrides | 3 |
-| `.no_toc` excluded | 4 (existing collect_headers) |
-| IDs match `--id-format` / manual IDs | 2, 4 |
-| Metadata `toc-min-max` | 6 |
-| Docs / man | 7 |
-| Empty doc behavior | 4 |
-| Invalid CLI values rejected | 5 |
-
-## Notes for implementers
-
-- `apex_markdown_to_html` is the library entry for all formats despite the name — follow existing early-return patterns for JSON/markdown.
-- Bare HTML TOC default change (1–6 → 1–3) is intentional; call it out in changelog with `@changed` when the user requests a commit message.
-- Do not add separate `--toc-min` / `--toc-max` flags.
-- Wiki lives in `/Users/ttscoff/Desktop/Code/apex.wiki` (separate git repo).