panatgithub_AnkiHeadingSync/docs/plugin-improvement-audit-report.md

Plugin Improvement Audit Report

1. Executive summary

This plugin is in a solid middle stage: the core sync engine is better structured than many Obsidian plugins, but product surface and failure recovery are still uneven.

• Overall maturity

  • Medium to high for core sync architecture.
  • Medium for user-facing completeness.
  • Medium-low for failure recovery resilience across restarts and AnkiConnect outages.

• Strongest parts

  • Layered runtime composition.
  • State-aware incremental indexing.
  • Explicit marker conflict detection instead of blind overwrite.
  • Rich parser and sync-path test coverage for core card types.

• Highest-risk parts

  • Pending write-back recovery is discarded on load.
  • Destructive reset paths and batch sync are not transaction-safe.
  • Runtime feature surface and settings surface are not aligned.
  • QA Group note-model strategy is split between active user-model sync and dormant managed-model code.

• Next 3 most valuable improvements

  1. Persist pendingWriteBack correctly across plugin reloads and add restart-recovery tests.
  2. Add explicit AnkiConnect timeout/health-check handling and friendlier offline UX.
  3. Unify runtime product authority: semantic QA visibility, QA Group model strategy, and note-type source of truth.

• Validation baseline observed during this audit run

  • git status --short: clean.
  • npm run lint: passed.
  • npm test: failing in current baseline; failures cluster in FileIndexerService, ManualSyncService, and ClearCurrentFileSyncedCardsUseCase tests.

2. Architecture map

See plugin-improvement-audit-architecture-map.md.

In short, the active runtime path is:

main.ts -> AnkiHeadingSyncPlugin.onload() -> use cases -> ManualSyncService / cleanup use cases -> domain services + infrastructure gateways -> persisted plugin state + markdown write-back.

3. Confirmed strengths

3.1 Clear runtime composition and layer boundaries

• Evidence
  • src/presentation/AnkiHeadingSyncPlugin.ts :: onload() wires repositories, gateways, use cases, and the setting tab in one place.
  • Domain parsing and marker logic live outside presentation code.
  • AnkiConnect calls are centralized in src/infrastructure/anki/AnkiConnectGateway.ts.
• Why this is strong
  • It keeps plugin lifecycle, orchestration, parsing, and I/O mostly separated.
  • It makes future refactors possible without rewriting the whole plugin.

3.2 Incremental indexing is state-aware, not brute-force only

• Evidence
  • src/application/services/FileIndexerService.ts :: indexRefs() skips rereads when fileStamp, deckRulesFingerprint, and known-card presence still match.
  • The same path restores cards and group blocks from persisted state for unchanged files.
• Why this is strong
  • Large-vault behavior is already being treated as an engineering problem.
  • Re-indexing work is avoided when nothing relevant changed.

3.3 Marker write-back uses optimistic concurrency instead of blind overwrite

• Evidence
  • src/infrastructure/obsidian/ObsidianVaultGateway.ts :: replaceMarkdownFile() reads current content and throws MarkdownWriteConflictError if it no longer matches the scanned content.
  • src/application/services/MarkdownWriteBackService.ts :: write() collects conflictFiles and pendingEntries instead of silently overwriting.
• Why this is strong
  • This prevents silent file corruption when a note changes after scan but before marker write-back.

3.4 Card and QA Group identity recovery paths are explicit

• Evidence
  • src/domain/manual-sync/services/CardIndexingService.ts :: resolveIdentity() recovers by marker, by state, and by pending write-back.
  • src/domain/manual-sync/services/CardIndexingService.ts :: resolveGroupIdentity() recovers QA Group notes by GI marker, by src, or by block hash.
• Why this is strong
  • Sync identity is not tied to a single fragile marker path.
  • The design anticipates marker deletion and partial state recovery.

3.5 Saved field mappings are validated against live model fields

• Evidence
  • src/application/services/NoteFieldMappingService.ts :: validateMapping() rejects missing or stale fields.
  • src/application/services/QaGroupFieldMappingService.ts :: validateMapping() rejects missing QA Group fields, duplicate usage, and stale slot references.
• Why this is strong
  • The plugin does not blindly trust stale settings.
  • Model drift is surfaced as a user-facing problem instead of silently writing wrong fields.

3.6 User-facing error and i18n plumbing is centralized

• Evidence
  • src/application/errors/PluginUserError.ts separates internal errors from localized user messages.
  • src/presentation/notices/NoticeService.ts consolidates summary rendering.
  • src/presentation/i18n/index.ts and src/presentation/i18n/messages/* provide a real translation dictionary instead of ad hoc strings.
• Why this is strong
  • Error surfaces are at least architecturally prepared for consistent UX.

3.7 Core sync modules have non-trivial targeted tests

• Evidence
  • src/application/services/ManualSyncService.test.ts
  • src/application/services/QaGroupSyncService.test.ts
  • src/infrastructure/anki/AnkiConnectGateway.test.ts
  • src/presentation/settings/PluginSettingTab.test.ts
• Why this is strong
  • The repository is not relying only on smoke tests or manual validation.

4. Confirmed problems

4.1 Pending write-back recovery is discarded on every load

• Severity: high
• Area: sync correctness
• Evidence from real code
  • src/application/services/MarkdownWriteBackService.ts :: write() creates pendingEntries when marker write-back conflicts or fails.
  • src/application/services/FileIndexerService.ts :: indexRefs() explicitly consumes state.pendingWriteBack to force reread/recovery.
  • src/infrastructure/persistence/DataJsonPluginStateRepository.ts :: migratePluginState() always returns pendingWriteBack: [], even when loading an existing PluginState.
  • src/infrastructure/persistence/DataJsonPluginStateRepository.test.ts currently asserts this behavior by expecting loaded.pendingWriteBack to equal [].
• Why it matters
  • The codebase already models deferred marker recovery, but restart/load drops that state.
  • A user who hits a write conflict, closes Obsidian, then retries loses the recovery queue.
• Recommended fix
  • Preserve modern pendingWriteBack entries on load.
  • Keep legacy migration handling separate from modern-state passthrough.
  • Add explicit schema-versioned migration logic if needed.
• Estimated implementation size: M
• Risk level: medium
• Suggested test coverage
  • Persist and reload modern pendingWriteBack entries unchanged.
  • Restart after write conflict should still re-attempt marker repair.

4.2 Semantic QA is active in runtime but hidden in settings

• Severity: high
• Area: UX
• Evidence from real code
  • src/application/config/PluginSettings.ts includes semantic-qa in CARD_TYPE_CONFIG_IDS and requires semanticQaNoteType.
  • src/domain/manual-sync/services/CardIndexingService.ts actively parses semantic QA blocks.
  • src/application/services/RenderConfigService.ts :: resolve() actively selects a semantic QA note type.
  • src/presentation/settings/PluginSettingTab.ts hardcodes VISIBLE_CARD_TYPE_CONFIG_IDS = ["basic", "qa-group", "cloze"].
  • src/presentation/settings/PluginSettingTab.test.ts explicitly expects semantic QA controls not to exist.
• Why it matters
  • Users can hit runtime semantic QA behavior without being able to fully configure, disable, or map it from the settings page.
  • This is a product-surface mismatch, not just a code-style issue.
• Recommended fix
  • Either surface semantic QA as a first-class configurable card type, or remove/disable the parser until a proper UI exists.
• Estimated implementation size: M
• Risk level: medium
• Suggested test coverage
  • Settings UI coverage for semantic QA controls.
  • End-to-end semantic QA sync with explicit note-type and field-mapping selection.

4.3 Rebuild index exists but is not exposed to users

• Severity: medium
• Area: UX
• Evidence from real code
  • src/presentation/AnkiHeadingSyncPlugin.ts :: onload() instantiates RebuildCardIndexUseCase.
  • src/presentation/AnkiHeadingSyncPlugin.ts :: runRebuildCardIndex() implements user-facing handling and notices.
  • src/presentation/commands/registerCommands.ts registers only 4 commands and does not register rebuild.
  • src/presentation/settings/PluginSettingTab.ts :: renderCommandsCard() lists only the 4 registered commands.
• Why it matters
  • A recovery-oriented feature exists in code but is unavailable in normal user flows.
  • That increases support burden and leaves state-recovery capability effectively dormant.
• Recommended fix
  • Add a command and a clearly labeled UI entry for rebuild index.
  • Document what rebuild does and does not do.
• Estimated implementation size: S
• Risk level: low
• Suggested test coverage
  • Command registration test.
  • Settings/UI test for rebuild trigger visibility.

4.4 QA Group model authority is split between active user-model sync and dormant managed-model code

• Severity: medium
• Area: architecture
• Evidence from real code
  • Active runtime QA Group sync uses src/application/services/QaGroupSyncService.ts plus settings.cardTypeConfigs["qa-group"].noteType and QaGroupFieldMappingService.
  • src/application/services/QaGroupModelService.ts, src/application/services/QaGroupModelDefinition.ts, and src/application/config/ManagedNoteModels.ts implement managed model creation for ObsiAnki QA Group 12.
  • Repository-wide search shows QaGroupModelService is only referenced by its own tests, not by production runtime.
  • src/presentation/i18n/messages/en.ts and zh.ts still describe QA Group as syncing into ObsiAnki QA Group 12.
• Why it matters
  • The repository currently carries two different product stories for QA Group.
  • That makes maintenance, documentation, and future migration decisions harder than necessary.
• Recommended fix
  • Decide one authority model:
    • fully user-selected QA Group models, or
    • plugin-managed QA Group model.
  • Remove or archive the losing branch.
  • Update settings copy accordingly.
• Estimated implementation size: M
• Risk level: medium
• Suggested test coverage
  • Remove dead branch tests or convert them into migration tests.
  • One integration path from settings to sync for the chosen authority model.

4.5 Settings UI is carrying too much stateful business logic in one file

• Severity: medium
• Area: architecture
• Evidence from real code
  • src/presentation/settings/PluginSettingTab.ts is roughly 1900 lines and owns:
    • note type cache loading
    • field cache hydration
    • QA Group derivation logic
    • debounced persistence
    • folder tree load/cache/expansion
    • card rendering and rerendering
  • The same class directly calls plugin.updateSettings() from many render-time control handlers.
• Why it matters
  • The file is already large enough that small changes can easily affect unrelated behavior.
  • UI, cache, mapping, and persistence concerns are mixed.
• Recommended fix
  • Split the setting tab into smaller card-focused modules and move mapping/cache orchestration into dedicated presenter/service helpers.
• Estimated implementation size: L
• Risk level: medium
• Suggested test coverage
  • Preserve existing UI tests while splitting into smaller component-level tests.
  • Add a render-count or localized-rerender test for card-scoped updates.

4.6 Legacy mirrored note-type fields still act as a shadow configuration path

• Severity: medium
• Area: architecture
• Evidence from real code
  • src/application/config/PluginSettings.ts stores both cardTypeConfigs[*].noteType and legacy fields such as qaNoteType, clozeNoteType, and semanticQaNoteType.
  • normalizePluginSettings() derives the legacy fields back from cardTypeConfigs.
  • src/application/services/RenderConfigService.ts :: resolveNoteModel() reads the legacy fields instead of cardTypeConfigs.
• Why it matters
  • There are two representations for the same concept.
  • The code currently avoids divergence only by normalization discipline, which is weaker than having one source of truth.
• Recommended fix
  • Make cardTypeConfigs the only runtime authority.
  • Relegate legacy fields to one-way migration only.
• Estimated implementation size: M
• Risk level: medium
• Suggested test coverage
  • Migration tests from old settings snapshots.
  • Runtime note-model resolution tests that use only cardTypeConfigs.

4.7 AnkiConnect failures are not classified into health-check/offline UX

• Severity: medium
• Area: UX
• Evidence from real code
  • src/infrastructure/anki/AnkiConnectGateway.ts :: invoke() calls requestUrl() without an explicit timeout parameter.
  • src/presentation/AnkiHeadingSyncPlugin.ts :: runSyncCurrentFile() and runSyncVault() catch generic errors and pass them through renderUnknownUserFacingError().
  • src/application/errors/PluginUserError.ts :: toUserFacingMessage() falls back to raw error text for ordinary Error instances.
• Why it matters
  • “Anki is not running”, “wrong URL”, “timed out”, and “AnkiConnect returned an action error” are different user problems but converge to a generic failure path.
  • This weakens first-run UX and troubleshooting.
• Recommended fix
  • Add a dedicated gateway health-check method, explicit timeout handling, and user-facing offline messaging.
  • Surface that in settings as a check button or status line.
• Estimated implementation size: M
• Risk level: low
• Suggested test coverage
  • Gateway timeout test.
  • Plugin-level offline error rendering test.
  • Settings health-check UI test.

4.8 Clear-current-file reset deletes remote notes before markdown cleanup succeeds

• Severity: high
• Area: sync correctness
• Evidence from real code
  • src/application/use-cases/ClearCurrentFileSyncedCardsUseCase.ts :: execute() deletes note IDs through ankiGateway.deleteNotes(noteIds) before calling markdownMarkerRemovalService.remove(...).
  • The result can still contain conflictFiles and failureFiles, meaning markdown cleanup can fail after remote deletion has already happened.
• Why it matters
  • A user can end up with deleted Anki notes but stale markers/local traces in Markdown.
  • There is no rollback path.
• Recommended fix
  • Make reset more recoverable:
    • either remove local markers/state first and mark remote deletion as pending,
    • or add a two-phase result model with resumable cleanup.
• Estimated implementation size: M
• Risk level: high
• Suggested test coverage
  • Conflict during marker removal after remote deletion.
  • Restart/resume after partial reset.

4.9 Batch sync is non-transactional across create/update/tag/deck/media phases

• Severity: high
• Area: sync correctness
• Evidence from real code
  • src/application/services/AnkiBatchExecutor.ts :: execute() performs deck ensure, media upload, note create, note update, model migration, tag sync, and deck migration in separate phases.
  • There is no rollback or checkpoint reconciliation when a later phase fails after earlier remote mutations already succeeded.
• Why it matters
  • Partial AnkiConnect failure can leave the remote state ahead of the local marker/state write-back pipeline.
  • The plugin already tries to recover marker writes, but not the whole multi-phase sync transaction.
• Recommended fix
  • Introduce a resumable execution journal or a narrower phase-by-phase recovery strategy.
  • At minimum, classify remote progress in the saved state when later phases fail.
• Estimated implementation size: L
• Risk level: high
• Suggested test coverage
  • Partial failure after note creation but before tag/deck sync.
  • Partial failure after model migration.

4.10 Test doubles are too optimistic for real Anki multi-request failure behavior

• Severity: medium
• Area: testing
• Evidence from real code
  • src/test-support/manualSyncFakes.ts :: FakeManualSyncAnkiGateway batch methods (addNotes, updateNotes, changeDecks, storeMediaFiles) always succeed and do not simulate per-item or top-level multi failures.
  • The real adapter in src/infrastructure/anki/AnkiConnectGateway.ts uses multi requests and already contains per-item error parsing logic for some actions.
• Why it matters
  • Service-level tests can pass while still underrepresenting real-world failure modes.
  • This is one reason the code has many happy-path tests but weaker evidence around partial remote failures.
• Recommended fix
  • Add failure-capable fake gateways or integration-style adapter fixtures that can simulate:
    • top-level multi errors
    • partial per-action failures
    • timeouts / transport errors
• Estimated implementation size: M
• Risk level: low
• Suggested test coverage
  • AnkiBatchExecutor partial failure cases.
  • ManualSyncService recovery after transport failure.

5. Improvement backlog

P0: must fix soon

• Persist pendingWriteBack on load and restart.
• Harden destructive reset so remote deletion cannot silently outrun local cleanup.
• Add AnkiConnect timeout/health classification and user-facing offline guidance.
• Add at least one resumable or checkpointed strategy for partial remote sync failure.

P1: high value

• Resolve semantic QA runtime/UI mismatch.
• Unify QA Group model authority and remove dormant managed-model branch or fully adopt it.
• Collapse note-model authority onto cardTypeConfigs only.
• Expose rebuild index or remove the dormant entry point.
• Refactor PluginSettingTab into smaller modules.
• Improve failure-capable test doubles and add failure-path integration tests.

P2: nice to have

• Improve locale handling so zh-* variants do not fall back to English by design.
• Move query_note.js and query_notes.js into an explicit debug/scripts area or remove them.
• Simplify build/release documentation around root main.js vs dist/plugin/main.js.
• Add a small settings-page connection test/diagnostic panel.

P3: later exploration

• Dry-run or preview mode before sync.
• Richer conflict explanation UI for marker-write conflicts.
• Lightweight performance telemetry for large-vault scans.

6. Recommended next development plans

Module 1: Persist pending write-back across restart

• Goal
  • Make marker conflict recovery survive plugin reloads.
• Why it matters
  • The current design already depends on pendingWriteBack, but load discards it.
• Files likely to change
  • src/infrastructure/persistence/DataJsonPluginStateRepository.ts
  • src/infrastructure/persistence/DataJsonPluginStateRepository.test.ts
  • Possibly src/domain/manual-sync/entities/PluginState.ts
• Implementation outline
  • Distinguish legacy migration from modern-state passthrough.
  • Preserve modern pendingWriteBack entries.
  • Validate marker kinds and required fields on load.
• Tests to add
  • Save/load round-trip for modern pending entries.
  • Recovery after conflict across repository reload.
• Risk
  • Medium
• Suggested prompt title
  • Persist Pending Writeback Recovery

Module 2: Add Anki health check and timeout-aware UX

• Goal
  • Turn Anki offline/slow scenarios into clear, recoverable UX.
• Why it matters
  • Current transport errors are too generic for first-run and troubleshooting.
• Files likely to change
  • src/infrastructure/anki/AnkiConnectGateway.ts
  • src/presentation/AnkiHeadingSyncPlugin.ts
  • src/presentation/settings/PluginSettingTab.ts
  • src/presentation/i18n/messages/en.ts
  • src/presentation/i18n/messages/zh.ts
• Implementation outline
  • Add ping/health-check action.
  • Add explicit timeout handling.
  • Surface health result in settings and sync command failures.
• Tests to add
  • Gateway timeout/offline tests.
  • Settings health-check UI tests.
  • Plugin command offline-notice tests.
• Risk
  • Low
• Suggested prompt title
  • AnkiConnect Health Check UX

Module 3: Bring semantic QA to product parity

• Goal
  • Stop having semantic QA exist only half-way between runtime and settings.
• Why it matters
  • Users need explicit control over all active sync-capable card types.
• Files likely to change
  • src/presentation/settings/PluginSettingTab.ts
  • src/presentation/settings/PluginSettingTab.test.ts
  • src/application/config/PluginSettings.ts
  • src/application/services/NoteFieldMappingService.ts
  • src/application/services/RenderConfigService.ts
• Implementation outline
  • Expose semantic QA in settings with note-type and field mapping.
  • Or gate parser/runtime support behind explicit availability.
• Tests to add
  • Settings rendering and persistence tests.
  • Semantic QA sync path with configured mapping.
• Risk
  • Medium
• Suggested prompt title
  • Semantic QA Settings Parity

Module 4: Harden clear-current-file reset

• Goal
  • Make reset resumable and safer under write conflicts or partial failures.
• Why it matters
  • Current order can delete remote data before local cleanup finishes.
• Files likely to change
  • src/application/use-cases/ClearCurrentFileSyncedCardsUseCase.ts
  • src/application/services/MarkdownSyncedMarkerRemovalService.ts
  • src/infrastructure/persistence/DataJsonPluginStateRepository.ts
  • src/application/use-cases/ClearCurrentFileSyncedCardsUseCase.test.ts
• Implementation outline
  • Add staged reset state or reorder the operation with recovery markers.
  • Preserve enough local state to retry cleanup safely.
• Tests to add
  • Conflict after remote delete.
  • Retry after restart.
• Risk
  • High
• Suggested prompt title
  • Harden Clear Current File Reset

Module 5: Unify QA Group model authority

• Goal
  • Remove the split between user-selected QA Group models and dormant managed-model infrastructure.
• Why it matters
  • One codebase should tell one consistent QA Group story.
• Files likely to change
  • src/application/services/QaGroupModelService.ts
  • src/application/services/QaGroupModelDefinition.ts
  • src/application/config/ManagedNoteModels.ts
  • src/application/services/QaGroupSyncService.ts
  • src/presentation/settings/PluginSettingTab.ts
  • src/presentation/i18n/messages/en.ts
  • src/presentation/i18n/messages/zh.ts
• Implementation outline
  • Decide whether the plugin owns a managed QA Group model.
  • Remove or fully integrate the losing branch.
• Tests to add
  • End-to-end QA Group path for the chosen authority model.
  • Copy and settings tests matching the chosen UX.
• Risk
  • Medium
• Suggested prompt title
  • Unify QA Group Model Authority

Module 6: Make cardTypeConfigs the sole note-model authority

• Goal
  • Complete the settings migration instead of keeping mirrored legacy fields alive.
• Why it matters
  • Shadow settings make future bugs more likely.
• Files likely to change
  • src/application/config/PluginSettings.ts
  • src/application/services/RenderConfigService.ts
  • src/infrastructure/persistence/DataJsonPluginConfigRepository.ts
  • src/application/config/PluginSettings.test.ts
• Implementation outline
  • Read note-model names directly from cardTypeConfigs.
  • Keep legacy values only for load-time migration.
• Tests to add
  • Old snapshot migration tests.
  • RenderConfigService tests for all card types.
• Risk
  • Medium
• Suggested prompt title
  • Retire Legacy Note Type Mirrors

Module 7: Split the settings page by card and service

• Goal
  • Reduce the size and cognitive load of PluginSettingTab.ts.
• Why it matters
  • The settings page is now one of the main maintenance hotspots.
• Files likely to change
  • src/presentation/settings/PluginSettingTab.ts
  • New helpers/components under src/presentation/settings/
  • src/presentation/settings/PluginSettingTab.test.ts
• Implementation outline
  • Extract card-type card, deck card, scope card, and cache/mapping orchestration helpers.
  • Keep public UI behavior stable first.
• Tests to add
  • Preserve existing behavior with smaller focused tests.
• Risk
  • Medium
• Suggested prompt title
  • Refactor Settings Page Cards

7. Product suggestions

• Simplify settings mental model

  • Make every active sync-capable card type visible and configurable from one consistent card-type surface.

• Improve onboarding

  • Add a first-run AnkiConnect health check and a “what still needs configuration” summary.

• Add sync preview or dry-run mode

  • The existing plan/build architecture is already close to supporting a non-destructive preview step.

• Make error recovery explicit

  • Marker-write conflicts should tell the user what happened, what was already synced remotely, and how to retry safely.

• Add mapping confidence cues

  • Show whether a mapping is from live cache, stale cache, manual override, or incomplete selection.

• Explain conflicts in UI

  • Deck fallback warnings and mapping staleness already exist in code; present them earlier in settings or pre-sync diagnostics.

• Stop hardcoding old QA Group product language in user copy

  • Current strings still refer to ObsiAnki QA Group 12 even though runtime sync now follows user-selected models.

8. Technical suggestions

• Tighten service boundaries

  • Move settings-page cache and mapping orchestration out of PluginSettingTab.

• Finish config migration

  • Keep one note-model authority path and one QA Group model strategy.

• Strengthen state invariants

  • pendingWriteBack should be durable, validated, and part of the explicit recovery model.

• Harden gateway contracts

  • Distinguish transport failure, top-level AnkiConnect error, and per-action multi failure.

• Clean dead or dormant branches

  • Remove unmanaged remnants like unused managed QA Group runtime services if they are not the chosen direction.

• Add lightweight performance instrumentation

  • File scan counts, skipped counts, and marker-conflict counts are already available and could be logged or surfaced in debug mode.

9. Testing suggestions

Parser

• Add more pathological QA Group and semantic QA markdown cases:
  • mixed fences
  • repeated labels
  • ambiguous indentation
  • empty answer edge cases

Mapping

• Add stale-field and partially renamed-field tests for basic, cloze, semantic QA, and QA Group mappings.
• Add tests for semantic QA settings once surfaced.

Sync execution

• Add partial failure tests after remote note creation but before local write-back.
• Add restart/retry tests using persisted pendingWriteBack.

Anki gateway

• Add timeout/offline tests.
• Add explicit multi partial failure tests for more actions than model-field loading.

Settings UI

• Add tests for semantic QA controls if kept active.
• Add health-check and stale-cache status tests.

Persistence / migration

• Add save/load tests that preserve pendingWriteBack.
• Add versioned migration tests for old settings snapshots after legacy field cleanup.

Failure paths

• Add reset-conflict tests where remote deletion succeeds but local cleanup fails.
• Add deck cleanup partial-failure tests with mixed deletion outcomes.

E2E / manual validation

• Validate against a real Anki instance for:
  • Anki offline
  • changed note model fields
  • QA Group model mismatch
  • marker conflict after editing the file between scan and write-back

10. Risks and non-goals

• Do not rewrite the whole plugin.
• Do not add more settings before fixing the current runtime/UI mismatches.
• Do not keep both user-selected QA Group models and dormant managed QA Group model code long term.
• Do not hide AnkiConnect transport errors under vague generic notices.
• Do not overfit field mapping heuristics to one language or one note template.
• Do not treat generated main.js or dist/plugin/* as the primary design surface.

11. Quick wins

• Add a rebuild-index command and list it in the settings command card.
• Treat zh-CN / zh-TW style locales as Chinese instead of falling back to English.
• Move query_note.js and query_notes.js under a scripts/debug/ convention or delete them.
• Update QA Group settings copy to match the actual chosen product model.
• Add a settings-page “Check Anki connection” button.

12. Suggested implementation order

1. Persist pendingWriteBack correctly across save/load/restart.
2. Add AnkiConnect timeout + health-check + offline UX.
3. Harden clear-current-file reset against partial failure.
4. Resolve semantic QA runtime/UI mismatch.
5. Unify QA Group model authority.
6. Retire legacy note-type mirrors and make cardTypeConfigs authoritative.
7. Improve failure-capable test doubles and add partial-failure integration coverage.
8. Split the settings page into smaller card-scoped modules.