fix(sync): Show fresh sync option when migration wizard has no baseline snapshot

When a character references a ruleset snapshot that doesn't exist on disk,
the drift analyzer now sets noBaseline: true on the empty report. The
MigrationWizard detects this and shows a "Sync to Current Rules" button
instead of an empty changes list, allowing the user to create a baseline
snapshot and resolve the red stability shield.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Jasrags

app/api/characters/[characterId]/sync/migrate/route.ts

@@ -12,12 +12,14 @@
 
 import { NextRequest, NextResponse } from "next/server";
 import { getSession } from "@/lib/auth/session";
-import { getCharacterById, rollbackMigration } from "@/lib/storage/characters";
+import { getCharacterById, updateCharacter, rollbackMigration } from "@/lib/storage/characters";
+import { captureRulesetSnapshot } from "@/lib/storage/ruleset-snapshots";
 import { executeMigration, validateMigrationPlan } from "@/lib/rules/sync/migration-engine";
 import {
   recordMigrationStart,
   recordMigrationComplete,
   recordMigrationRollback,
+  recordManualResync,
 } from "@/lib/rules/sync/sync-audit";
 import type { MigrationPlan } from "@/lib/types";
 
@@ -55,6 +57,26 @@ export async function POST(request: NextRequest, { params }: RouteParams): Promi
 
     // Parse request body
     const body = await request.json();
+
+    // Fresh sync: create baseline snapshot for characters with no existing snapshot
+    if (body.freshSync === true) {
+      const versionRef = await captureRulesetSnapshot(character.editionCode);
+      const now = new Date().toISOString();
+
+      await updateCharacter(userId, characterId, {
+        rulesetSnapshotId: versionRef.snapshotId,
+        rulesetVersion: versionRef,
+        syncStatus: "synchronized",
+        legalityStatus: "rules-legal",
+        lastSyncAt: now,
+        lastSyncCheck: now,
+      });
+
+      await recordManualResync(userId, character, versionRef);
+
+      return NextResponse.json({ success: true, freshSync: true });
+    }
+
     const plan = body.plan as MigrationPlan;
 
     if (!plan) {

components/sync/MigrationWizard.tsx

@@ -39,6 +39,7 @@ interface MigrationWizardProps {
 export function MigrationWizard({ characterId, onClose, onComplete }: MigrationWizardProps) {
   const wizard = useMigrationWizard(characterId);
   const [isApplying, setIsApplying] = useState(false);
+  const [isSyncing, setIsSyncing] = useState(false);
 
   // Get breaking changes that need decisions
   const breakingChanges = wizard.report?.changes.filter((c) => c.severity === "breaking") || [];
@@ -61,6 +62,24 @@ export function MigrationWizard({ characterId, onClose, onComplete }: MigrationW
     }
   };
 
+  const handleFreshSync = async () => {
+    setIsSyncing(true);
+    try {
+      const response = await fetch(`/api/characters/${characterId}/sync/migrate`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ freshSync: true }),
+      });
+
+      if (response.ok) {
+        onComplete?.();
+        onClose();
+      }
+    } finally {
+      setIsSyncing(false);
+    }
+  };
+
   if (!wizard.report) {
     return (
       <WizardContainer onClose={onClose}>
@@ -71,19 +90,28 @@ export function MigrationWizard({ characterId, onClose, onComplete }: MigrationW
     );
   }
 
+  const isNoBaseline = wizard.report.noBaseline && wizard.report.changes.length === 0;
+
   return (
     <WizardContainer onClose={onClose}>
       {/* Progress indicator */}
-      <WizardProgress
-        currentStep={wizard.currentStep}
-        totalSteps={wizard.totalSteps}
-        breakingChanges={breakingChanges.length}
-      />
+      {!isNoBaseline && (
+        <WizardProgress
+          currentStep={wizard.currentStep}
+          totalSteps={wizard.totalSteps}
+          breakingChanges={breakingChanges.length}
+        />
+      )}
 
       {/* Content area */}
       <div className="p-6">
         {wizard.currentStep === 0 && (
-          <ReviewStep report={wizard.report} breakingCount={breakingChanges.length} />
+          <ReviewStep
+            report={wizard.report}
+            breakingCount={breakingChanges.length}
+            onFreshSync={isNoBaseline ? handleFreshSync : undefined}
+            isSyncing={isSyncing}
+          />
         )}
 
         {currentChange && (
@@ -101,17 +129,19 @@ export function MigrationWizard({ characterId, onClose, onComplete }: MigrationW
         )}
       </div>
 
-      {/* Footer with navigation */}
-      <WizardFooter
-        currentStep={wizard.currentStep}
-        totalSteps={wizard.totalSteps}
-        canApply={wizard.canApply}
-        isApplying={isApplying}
-        onPrev={wizard.prevStep}
-        onNext={wizard.nextStep}
-        onApply={handleApply}
-        onCancel={onClose}
-      />
+      {/* Footer with navigation (hidden when showing fresh sync UI) */}
+      {!isNoBaseline && (
+        <WizardFooter
+          currentStep={wizard.currentStep}
+          totalSteps={wizard.totalSteps}
+          canApply={wizard.canApply}
+          isApplying={isApplying}
+          onPrev={wizard.prevStep}
+          onNext={wizard.nextStep}
+          onApply={handleApply}
+          onCancel={onClose}
+        />
+      )}
     </WizardContainer>
   );
 }
@@ -226,11 +256,47 @@ function WizardProgress({ currentStep, totalSteps, breakingChanges }: WizardProg
 // =============================================================================
 
 interface ReviewStepProps {
-  report: { changes: DriftChange[] };
+  report: { changes: DriftChange[]; noBaseline?: boolean };
   breakingCount: number;
+  onFreshSync?: () => void;
+  isSyncing?: boolean;
 }
 
-function ReviewStep({ report, breakingCount }: ReviewStepProps) {
+function ReviewStep({ report, breakingCount, onFreshSync, isSyncing }: ReviewStepProps) {
+  // No baseline: show fresh sync UI
+  if (report.noBaseline && report.changes.length === 0 && onFreshSync) {
+    return (
+      <div className="space-y-6">
+        <div>
+          <h3 className="text-lg font-medium text-gray-900 dark:text-white mb-2">
+            Ruleset Snapshot Missing
+          </h3>
+          <p className="text-sm text-gray-500 dark:text-gray-400">
+            This character references a ruleset snapshot that no longer exists. This can happen when
+            a character was created before the snapshot system was set up.
+          </p>
+        </div>
+
+        <div className="bg-blue-50 dark:bg-blue-900/20 rounded-lg p-4">
+          <p className="text-sm text-blue-700 dark:text-blue-300 mb-4">
+            Sync to the current rules to create a baseline snapshot. Future ruleset changes will be
+            tracked against this baseline.
+          </p>
+          <button
+            onClick={onFreshSync}
+            disabled={isSyncing}
+            className={`
+              px-4 py-2 text-sm font-medium text-white rounded-lg
+              ${isSyncing ? "bg-gray-400 cursor-not-allowed" : "bg-blue-600 hover:bg-blue-700"}
+            `}
+          >
+            {isSyncing ? "Syncing..." : "Sync to Current Rules"}
+          </button>
+        </div>
+      </div>
+    );
+  }
+
   const nonBreaking = report.changes.filter((c) => c.severity !== "breaking");
   const breaking = report.changes.filter((c) => c.severity === "breaking");
 

lib/rules/sync/__tests__/drift-analyzer.test.ts

@@ -165,7 +165,7 @@ describe("Drift Analyzer", () => {
   // ===========================================================================
 
   describe("analyzeCharacterDrift", () => {
-    it("should return empty report when no current snapshot exists for edition", async () => {
+    it("should return empty report with noBaseline when no current snapshot exists for edition", async () => {
       const character = createMockCharacter({
         editionCode: "sr5",
         rulesetSnapshotId: "old-snapshot",
@@ -177,9 +177,10 @@ describe("Drift Analyzer", () => {
 
       expect(report.changes).toEqual([]);
       expect(report.overallSeverity).toBe("none");
+      expect(report.noBaseline).toBe(true);
     });
 
-    it("should return empty report when character already on current snapshot", async () => {
+    it("should return empty report without noBaseline when character already on current snapshot", async () => {
       const character = createMockCharacter({
         editionCode: "sr5",
         rulesetSnapshotId: "current-snapshot",
@@ -193,11 +194,12 @@ describe("Drift Analyzer", () => {
 
       expect(report.changes).toEqual([]);
       expect(report.overallSeverity).toBe("none");
+      expect(report.noBaseline).toBeFalsy();
       // Should not load full snapshots
       expect(getRulesetSnapshot).not.toHaveBeenCalled();
     });
 
-    it("should return empty report when character snapshot not found", async () => {
+    it("should return empty report with noBaseline when character snapshot not found", async () => {
       const character = createMockCharacter({
         editionCode: "sr5",
         rulesetSnapshotId: "missing-snapshot",
@@ -212,6 +214,7 @@ describe("Drift Analyzer", () => {
 
       expect(report.changes).toEqual([]);
       expect(report.overallSeverity).toBe("none");
+      expect(report.noBaseline).toBe(true);
     });
 
     it("should throw when current ruleset snapshot not found", async () => {

lib/rules/sync/drift-analyzer.ts

@@ -669,6 +669,7 @@ function createEmptyDriftReportNoBaseline(character: Character): DriftReport {
     overallSeverity: "none",
     changes: [],
     recommendations: [],
+    noBaseline: true,
   };
 }
 

lib/types/synchronization.ts

@@ -96,6 +96,8 @@ export interface DriftReport {
   changes: DriftChange[];
   /** Recommended migration actions */
   recommendations: MigrationRecommendation[];
+  /** True when no baseline snapshot exists (missing or never captured) */
+  noBaseline?: boolean;
 }
 
 /**