Clarify current Karabiner migration boundaries

[malpern]

What changed

Clarifies the current Karabiner migration boundary without promising future parity. The migration guide now distinguishes supported, limited, and deferred Karabiner capabilities, removes the temporary-loss and unsupported 95% conversion language, and documents importer-specific limits plus skipped-rule review and original-config backup guidance. The installation guide links to the boundary section.

Validation

• git diff --check
• Focused frontmatter/link/scope assertions
• Preserved-feature source checks
• PATH=/usr/bin:/bin ./Scripts/review-gate.sh → remote review gate selected (exit 2)

No Swift build, tests, publishing, or merge performed.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-06T16:46:20.760311Z	e3dae5c	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[claude]

Docs-only change, mostly good (dropping the unverifiable "~95%"/"19 packs"/"16 collections" figures reduces staleness risk). One thing worth double-checking before merge:

migration/karabiner-users.md, "Config import" section — this PR adds a new, more specific claim that wasn't previously stated anywhere in the doc:

The importer accepts Karabiner JSON or a complex-modifications rule file; Goku EDN is outside this importer path.

This introduces Goku by name for the first time in the guide with no prior context on what it is, and asserts a specific in/out-of-scope boundary for the importer (Karabiner JSON + complex-modifications rule file = supported, Goku EDN = not supported). Since this is a factual claim about importer behavior rather than a wording/terminology cleanup like the rest of the diff, please confirm it's accurate against the actual keypath import karabiner implementation before merging — if it's wrong, it's now the most specific (and therefore most trusted) statement in the doc about what the converter accepts.

No other actionable issues found in the diff.

[malpern]

Confirmed against the current implementation. keypath import karabiner declares its positional input as karabiner.json or complex_modifications rule file in Sources/KeyPathCLI/Commands/Import/ImportKarabinerCommand.swift:13.

The normal path is CollectionsFacade.importFromKarabiner (Sources/KeyPathAppKit/CLI/CollectionsFacade.swift:226-231), which calls KarabinerConverterService.convert. That service decodes KarabinerConfig with JSONDecoder (Sources/KeyPathAppKit/Services/Karabiner/KarabinerConverterService.swift:105-112) and converts a selected profile (:79-100). If that fails, the CLI-only fallback accepts a JSON object containing rules, wraps it as a selected Karabiner profile, and passes it back through the same converter (CollectionsFacade.swift:285-307).

Goku EDN is therefore outside this importer path: the accepted inputs are JSON, and there is no EDN parser or Goku conversion branch in the command/facade/converter path. Skipped rules are carried into the CLI result at CollectionsFacade.swift:265-273; the CLI prints each description/reason at ImportKarabinerCommand.swift:110-115, and the wizard surfaces the skipped count at WizardKarabinerImportPage.swift:139-143. No inline review comments were present.

[claude]

Doc-only PR, changes read well overall. One thing worth double-checking before merge:

• migration/karabiner-users.md: the diff swaps a soft, unverifiable claim ("~95% of typical configs convert") for two new, more specific behavioral claims: (1) "It reports rules that it skips and the reason for each skip" and (2) "The importer accepts Karabiner JSON or a complex-modifications rule file; Goku EDN is outside this importer path." These are good improvements if accurate, but they're now testable assertions about the CLI importer's actual behavior (per-rule skip reasons, JSON/complex-mods support, explicit non-support of Goku EDN). Please confirm these match the current importer implementation — if the importer only reports skip counts rather than a reason per rule, or if Goku EDN parsing exists/doesn't exist as described, the docs would be misleading users about what to expect from keypath import karabiner.

No other correctness issues spotted; the terminology changes (Full support/Partial/Not yet → Supported/Limited/Deferred, dropping the hard-coded pack counts of 19 vs 16 which were inconsistent) look like a net improvement.

[malpern]

Rechecked after rebase at f83dc4c: the earlier implementation evidence still applies. ImportKarabinerCommand.swift lines 110–115 iterates result.skippedRules and prints each description and reason, so this is per-rule reporting, not only a count. The accepted JSON/full-profile and complex-modifications fallback paths, and absence of an EDN parser on that path, are detailed in the preceding source confirmation. Both behavioral claims are verified.