Edge cases

Notes on unusual situations and how the tool behaves.

Solved

Problems we hit early and fixed deliberately:

• Per-file const maps for static keys — why merged-repo scans are weaker than per-file scans for template rebuilds.
• CLI --json command parity — COMMANDS_WITH_JSON_OUTPUT vs human-only paths; printCommandSummary / single-document stdout for scripts.
• Sync metadata flag conflict — --strip-metadata wins; metadata_flag_conflict warning.
• Generate --resume contract — partial leaf fill vs provider cache layers.
• Share hash dedup and --force — reuse remote ids; link rotation with --force.
• Locale layout mismatch rebuild — layout fingerprint → full scan.
• CI non-interactive gates — --yes, --json, non-TTY share/cleanup behavior.

Unsolved / planning

Long-horizon analysis and policy sketches (not shipped fixes yet):

• Unsolved hub — index; policy framework — FP/FN framing and future config ideas.

When to add a page

Add a solved/ page when:

• The bug or confusion was real in production or review, and
• The fix is stable and worth remembering for future contributors and agents.

Skip documenting one-off test quirks unless they affect users.