docs: 12 improvement ideas from automated audit

documentation/ideas-to-consider.md

@@ -144,3 +144,121 @@
   What: this.app.metadataCache.off("resolved", () => null) passes anonymous fn that never matches.
     Listener never removed. Check if still present in src/main.ts.
   Descision: Accepted. Add to the book of work
+
+
+  Tier 5: Automated audit (2026-02-19)
+
+  #: 18
+  Item: Unit tests for stateless helpers (offset-mapper, block-id, markdown-strip)
+  Source: Automated audit
+  What: Pure utility modules in src/stateless-helpers/ have no dedicated test files. offset-mapper.ts
+    has complex offset remapping logic, block-id.ts has parsing, markdown-strip.ts does markdown
+    cleaning. All are pure functions — trivial to test with no Obsidian runtime deps.
+    Complements #15 (unit test coverage expansion) with specific targets.
+  Priority: P1
+
+  ────────────────────────────────────────
+  #: 19
+  Item: OverlayManager test coverage
+  Source: Automated audit
+  What: src/managers/overlay-manager/ has zero test files despite being a complex orchestrator
+    (selection toolbar, bottom toolbar, context menu, edge zones, action click dispatch). Add
+    smoke tests for init/teardown lifecycle, workspace event handling, and action click routing.
+  Priority: P1
+
+  ────────────────────────────────────────
+  #: 20
+  Item: Extract magic numbers to named constants in event coalescing
+  Source: Automated audit
+  What: Hardcoded 250ms quiet window and 2000ms max window in bulk-event-emmiter.ts, 5000ms TTL
+    in self-event-tracker.ts, 500ms navigation timeout in cd.ts. Extract to named constants with
+    comments explaining the rationale for each value.
+  Priority: P2
+
+  ────────────────────────────────────────
+  #: 21
+  Item: Wrap undocumented Obsidian API accesses in cd.ts
+  Source: Automated audit
+  What: cd.ts uses multiple `as unknown` casts to access undocumented APIs (leftSplit.collapsed,
+    app.commands.executeCommandById). Wrap these in a helper with try-catch and version comments
+    so Obsidian API drift surfaces cleanly instead of crashing.
+  Priority: P2
+
+  ────────────────────────────────────────
+  #: 22
+  Item: API error catch block improvement in api-service.ts
+  Source: Automated audit
+  What: Line ~199 in api-service.ts uses empty catch with `___errors` — error info is discarded.
+    Also, Promise.race() with timeout at line ~187 has non-obvious semantics (rejection from
+    postGoogleApi propagates through race). Consider capturing error details in the catch and
+    clarifying the timeout race pattern.
+  Priority: P2
+
+  ────────────────────────────────────────
+  #: 23
+  Item: Resolve calibration TODOs for numeric thresholds
+  Source: Automated audit
+  What: Several unresolved TODOs around tunable thresholds:
+    - multi-span.ts:74 "search radius is a tunable parameter"
+    - note-adapter.ts:134 "calibrate sampling cache size"
+    - propagate-morphemes.ts:72 "calibrate this threshold"
+    Either document current values with rationale or extract to a TUNABLE_PARAMS object.
+  Priority: P2
+
+  ────────────────────────────────────────
+  #: 24
+  Item: Document error handling decision tree
+  Source: Automated audit
+  What: Inconsistent patterns across codebase — some code uses logError() (auto-notice + log),
+    some uses raw logger.error(), some catch blocks swallow silently. Add a brief section to
+    CLAUDE.md or a docs file with when to use each:
+    - Recoverable → neverthrow Result
+    - Unrecoverable → logError() with notice
+    - Expected → logger.warn()
+    - Debug → logger.info()
+  Priority: P2
+
+  ────────────────────────────────────────
+  #: 25
+  Item: Retry config per-API profile
+  Source: Automated audit
+  What: retry.ts has a single DEFAULT_CONFIG (1s base, 3 attempts, 2x multiplier). API service
+    has 45s timeout but uses generic retry. Allow passing custom retry profiles from ApiService
+    for different call types (e.g., generate vs cache creation).
+  Priority: P2
+
+  ────────────────────────────────────────
+  #: 26
+  Item: OverlayManager teardown verification
+  Source: Automated audit
+  What: overlay-manager.ts stores selectionHandlerTeardown as a closure. If plugin is disabled
+    without calling unload(), the handler reference persists in userEventInterceptor. Add explicit
+    verification that all teardowns fire during unload(), or log a warning if they don't.
+  Priority: P3
+
+  ────────────────────────────────────────
+  #: 27
+  Item: Suffix extraction consolidation
+  Source: Automated audit
+  What: Suffix parsing logic appears in multiple codec files (split-path-with-separated-suffix,
+    segment-id/parse.ts, wikilink.ts) with similar regex patterns. Consider extracting shared
+    extractSuffix()/splitNameAndSuffix() helpers to reduce maintenance burden.
+  Priority: P3
+
+  ────────────────────────────────────────
+  #: 28
+  Item: Self-event tracker prefix matching optimization
+  Source: Automated audit
+  What: self-event-tracker.ts iterates all tracked prefixes for every incoming event (O(n) per
+    event). For large vault operations with many folder renames, this could be slow. Consider a
+    trie or sorted-prefix binary search if profiling shows this as a bottleneck.
+  Priority: P3
+
+  ────────────────────────────────────────
+  #: 29
+  Item: Path aliases in tsconfig.json
+  Source: Automated audit
+  What: 15+ files have deep relative imports (4-5 levels: ../../../managers/obsidian/...).
+    Adding tsconfig path aliases (@managers/*, @commanders/*, @helpers/*) would improve
+    readability. Lower priority since it works fine as-is and has refactoring risk.
+  Priority: P3