docs + test: sync with --fix-index flip

Review follow-ups for PR #15:

- docs/realm-repair.md still documented the old `--no-fix-index`
  form after b9646da flipped the flag to `--fix-index`. Updated
  the description to match the new opt-in behavior and explain
  why it's off by default (breaks Checkly-style prerendering).

- test/commands/repair.test.ts had a misleading block titled
  "repair-realms batch defaults" that actually tested the
  handler's `?? false` fallback, not the commander CLI defaults.
  Renamed and clarified so it's obvious what it covers; the real
  commander-default coverage lives in the "commander flag parsing"
  block added in b9646da.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Chris

docs/realm-repair.md

@@ -33,7 +33,7 @@ boxel doctor repair-realm <url> \
 
 - `--match-endpoint`: force display name from endpoint slug (for example, `odd-sheep` -> `Odd Sheep`)
 - `--reconcile-matrix`: upsert/remove this specific realm URL in Matrix `app.boxel.realms`
-- `--no-fix-index`: skip `index.json` and `cards-grid.json` repairs
+- `--fix-index`: **opt-in.** Rewrite `index.json` and `cards-grid.json` starter cards. Off by default because this overwrites customized index files (which breaks things like Checkly prerendering that rely on a specific index shape). Only pass this when you know the realm has a standard index.
 - `--no-touch-index`: skip cache-busting mutation in `index.json`
 - `--include-personal`: include the special `personal` realm (excluded by default)
 

test/commands/repair.test.ts

@@ -113,28 +113,24 @@ describe('repair name logic', () => {
   });
 });
 
-describe('repair-realms batch defaults', () => {
-  it('defaults to not fixing index in batch mode', () => {
-    // Verify the default values match what we set in the code
+// NOTE: these tests check the handler-level `options.xxx ?? false` fallback
+// behavior when a caller (e.g. a test harness or programmatic invocation)
+// passes an empty options object. They do NOT cover the commander CLI
+// defaults — for that, see "repair commander flag parsing" below, which
+// parses commander directly and is the test that catches the real bug.
+describe('repair-realms handler fallback behavior', () => {
+  it('treats absent options.fixIndex as false', () => {
     const options: { fixIndex?: boolean; touchIndex?: boolean; matchEndpoint?: boolean } = {};
-    const fixIndex = options.fixIndex ?? false;
-    const touchIndex = options.touchIndex ?? false;
-    const matchEndpoint = options.matchEndpoint ?? false;
-
-    expect(fixIndex).toBe(false);
-    expect(touchIndex).toBe(false);
-    expect(matchEndpoint).toBe(false);
+    expect(options.fixIndex ?? false).toBe(false);
+    expect(options.touchIndex ?? false).toBe(false);
+    expect(options.matchEndpoint ?? false).toBe(false);
   });
 
-  it('respects explicit opt-in for index fixing', () => {
+  it('respects explicit opt-in', () => {
     const options = { fixIndex: true, touchIndex: true, matchEndpoint: true };
-    const fixIndex = options.fixIndex ?? false;
-    const touchIndex = options.touchIndex ?? false;
-    const matchEndpoint = options.matchEndpoint ?? false;
-
-    expect(fixIndex).toBe(true);
-    expect(touchIndex).toBe(true);
-    expect(matchEndpoint).toBe(true);
+    expect(options.fixIndex ?? false).toBe(true);
+    expect(options.touchIndex ?? false).toBe(true);
+    expect(options.matchEndpoint ?? false).toBe(true);
   });
 });