From c2ec363109e2cdde832b156f622c4c145ddd4741 Mon Sep 17 00:00:00 2001
From: Andre Manoel <amanoel@nvidia.com>
Date: Wed, 1 Jul 2026 15:00:19 -0300
Subject: [PATCH 1/4] fix: restore Fern fallback live reload

---
 fern/README.md                                |   6 +-
 fern/scripts/serve-local-docs-preview.py      | 137 +++++++++++++----
 .../tests/test_serve_local_docs_preview.py    | 145 ++++++++++++++++++
 .../local-preview-live-reload.md              |  71 +++++++++
 4 files changed, 327 insertions(+), 32 deletions(-)
 create mode 100644 fern/scripts/tests/test_serve_local_docs_preview.py
 create mode 100644 plans/fern-live-reload/local-preview-live-reload.md

diff --git a/fern/README.md b/fern/README.md
index ef0abd74c..af7704e0a 100644
--- a/fern/README.md
+++ b/fern/README.md
@@ -149,7 +149,9 @@ supports React's `<style precedence>` hoisting.
 
 The only checked-in standalone CSS is `styles/local-preview.css`, used by
 `make serve-fern-docs-locally` only when the Fern global theme is inaccessible.
-It is not referenced from `docs.yml`.
+It is not referenced from `docs.yml`. The fallback applies a deterministic
+NVIDIA-style local theme and mirrors source changes into Fern's temporary
+preview tree so live reload continues to work without theme access.
 
 ## Common commands
 
@@ -184,4 +186,4 @@ Raw Fern CLI commands, normally wrapped by Make:
 
 | Symptom | Fix |
 |---------|-----|
-| Local preview uses the local fallback theme | Sign in to https://dashboard.buildwithfern.com, run `cd fern && npx -y fern-api@$(jq -r .version fern.config.json) login`, then retry. If it still falls back, export a privileged `DOCS_FERN_TOKEN` as `FERN_TOKEN`. |
+| Local preview uses the deterministic local fallback theme | The fallback supports live reload without authentication. To use the canonical global theme, sign in to https://dashboard.buildwithfern.com, run `cd fern && npx -y fern-api@$(jq -r .version fern.config.json) login`, then retry. If it still falls back, export a privileged `DOCS_FERN_TOKEN` as `FERN_TOKEN`. |
diff --git a/fern/scripts/serve-local-docs-preview.py b/fern/scripts/serve-local-docs-preview.py
index 349f5872c..077fa2da8 100644
--- a/fern/scripts/serve-local-docs-preview.py
+++ b/fern/scripts/serve-local-docs-preview.py
@@ -7,6 +7,7 @@
 from __future__ import annotations
 
 import argparse
+import shutil
 import signal
 import subprocess
 import sys
@@ -41,6 +42,11 @@
 }
 
 COMPONENT_EXTENSIONS = {".js", ".jsx", ".ts", ".tsx"}
+DOCS_CONFIG_PATH = Path("docs.yml")
+POLL_INTERVAL_SECONDS = 0.25
+
+FileState = tuple[int, int, int]
+SourceState = dict[Path, FileState]
 
 
 def parse_args() -> argparse.Namespace:
@@ -81,43 +87,114 @@ def write_local_docs_config(root: Path, preview_root: Path) -> None:
     )
 
 
-def link_components(root: Path, preview_root: Path) -> None:
-    components_root = root / "components"
-    preview_components_root = preview_root / "components"
-    preview_components_root.mkdir()
-
-    for source in sorted(components_root.rglob("*")):
-        target = preview_components_root / source.relative_to(components_root)
-        if source.is_dir():
-            target.mkdir()
+def snapshot_source(root: Path) -> SourceState:
+    state = {}
+    for source in root.rglob("*"):
+        try:
+            if not source.is_file():
+                continue
+            stat = source.stat()
+        except FileNotFoundError:
             continue
+        state[source.relative_to(root)] = (stat.st_mtime_ns, stat.st_ino, stat.st_size)
+    return state
 
-        target.symlink_to(source)
-        if source.suffix in COMPONENT_EXTENSIONS:
-            alias = target.with_suffix("")
-            if not alias.exists():
-                alias.symlink_to(source)
 
-
-def build_preview_root(root: Path, preview_root: Path) -> None:
-    for child in root.iterdir():
-        if child.name == "docs.yml":
-            continue
-        target = preview_root / child.name
-        if child.name == "components":
-            link_components(root, preview_root)
+def component_aliases(state: SourceState) -> dict[Path, Path]:
+    aliases = {}
+    for source in state:
+        if source.parts[:1] != ("components",) or source.suffix not in COMPONENT_EXTENSIONS:
             continue
-        target.symlink_to(child, target_is_directory=child.is_dir())
-    write_local_docs_config(root, preview_root)
-
-
-def run_command(command: list[str], cwd: Path) -> int:
+        alias = source.with_suffix("")
+        if alias not in state:
+            aliases[alias] = source
+    return aliases
+
+
+def copy_preview_file(root: Path, preview_root: Path, source: Path, target: Path | None = None) -> None:
+    target = preview_root / (target or source)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(root / source, target)
+
+
+def remove_preview_file(preview_root: Path, relative_path: Path) -> None:
+    target = preview_root / relative_path
+    target.unlink(missing_ok=True)
+    parent = target.parent
+    while parent != preview_root:
+        try:
+            parent.rmdir()
+        except OSError:
+            break
+        parent = parent.parent
+
+
+def build_preview_root(root: Path, preview_root: Path) -> SourceState:
+    state = snapshot_source(root)
+    for relative_path in sorted(state):
+        if relative_path == DOCS_CONFIG_PATH:
+            write_local_docs_config(root, preview_root)
+        else:
+            copy_preview_file(root, preview_root, relative_path)
+    for alias, source in component_aliases(state).items():
+        copy_preview_file(root, preview_root, source, alias)
+    return state
+
+
+def sync_preview_root(root: Path, preview_root: Path, previous_state: SourceState) -> SourceState:
+    current_state = snapshot_source(root)
+    previous_aliases = component_aliases(previous_state)
+    current_aliases = component_aliases(current_state)
+    removed_paths = previous_state.keys() - current_state.keys()
+    removed_aliases = previous_aliases.keys() - current_aliases.keys()
+    for relative_path in sorted(removed_paths | removed_aliases):
+        remove_preview_file(preview_root, relative_path)
+
+    changed_paths = {
+        relative_path
+        for relative_path, file_state in current_state.items()
+        if previous_state.get(relative_path) != file_state
+    }
+    failed_paths = set()
+    for relative_path in sorted(changed_paths):
+        try:
+            if relative_path == DOCS_CONFIG_PATH:
+                write_local_docs_config(root, preview_root)
+            else:
+                copy_preview_file(root, preview_root, relative_path)
+        except FileNotFoundError:
+            failed_paths.add(relative_path)
+
+    changed_aliases = {
+        alias for alias, source in current_aliases.items() if alias not in previous_aliases or source in changed_paths
+    }
+    for alias in sorted(changed_aliases):
+        source = current_aliases[alias]
+        try:
+            copy_preview_file(root, preview_root, source, alias)
+        except FileNotFoundError:
+            failed_paths.add(source)
+
+    for relative_path in failed_paths:
+        current_state.pop(relative_path, None)
+    return current_state
+
+
+def run_command(command: list[str], cwd: Path, root: Path, source_state: SourceState) -> int:
     process = subprocess.Popen(command, cwd=cwd)
     try:
-        return process.wait()
+        while True:
+            try:
+                return process.wait(timeout=POLL_INTERVAL_SECONDS)
+            except subprocess.TimeoutExpired:
+                source_state = sync_preview_root(root, cwd, source_state)
     except KeyboardInterrupt:
         process.send_signal(signal.SIGINT)
         return process.wait()
+    except Exception:
+        process.send_signal(signal.SIGINT)
+        process.wait()
+        raise
 
 
 def main() -> int:
@@ -126,9 +203,9 @@ def main() -> int:
     with tempfile.TemporaryDirectory(prefix="fern-local-preview-") as temp_dir:
         preview_root = Path(temp_dir) / "fern"
         preview_root.mkdir()
-        build_preview_root(root, preview_root)
+        source_state = build_preview_root(root, preview_root)
         print(f"Using local Fern preview config at {preview_root / 'docs.yml'}", file=sys.stderr)
-        return run_command(args.command, preview_root)
+        return run_command(args.command, preview_root, root, source_state)
 
 
 if __name__ == "__main__":
diff --git a/fern/scripts/tests/test_serve_local_docs_preview.py b/fern/scripts/tests/test_serve_local_docs_preview.py
new file mode 100644
index 000000000..5f0c8a6f7
--- /dev/null
+++ b/fern/scripts/tests/test_serve_local_docs_preview.py
@@ -0,0 +1,145 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import importlib.util
+import subprocess
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+import yaml
+
+SCRIPT_PATH = Path(__file__).parents[1] / "serve-local-docs-preview.py"
+SPEC = importlib.util.spec_from_file_location("serve_local_docs_preview", SCRIPT_PATH)
+assert SPEC is not None and SPEC.loader is not None
+serve_local_docs_preview = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(serve_local_docs_preview)
+
+
+@pytest.fixture
+def docs_root(tmp_path: Path) -> Path:
+    root = tmp_path / "fern"
+    (root / "components").mkdir(parents=True)
+    (root / "styles").mkdir()
+    (root / "versions/latest/pages").mkdir(parents=True)
+    (root / "docs.yml").write_text(
+        yaml.safe_dump(
+            {
+                "global-theme": "nvidia",
+                "title": "Data Designer",
+                "css": "./styles/base.css",
+            },
+            sort_keys=False,
+        ),
+        encoding="utf-8",
+    )
+    (root / "components/Authors.tsx").write_text("export const Authors = 'initial';\n", encoding="utf-8")
+    (root / "styles/base.css").write_text("body {}\n", encoding="utf-8")
+    (root / "styles/local-preview.css").write_text(":root {}\n", encoding="utf-8")
+    (root / "versions/latest/pages/index.mdx").write_text("# Initial\n", encoding="utf-8")
+    return root
+
+
+def test_build_preview_root_materializes_local_theme(docs_root: Path, tmp_path: Path) -> None:
+    preview_root = tmp_path / "preview"
+    preview_root.mkdir()
+
+    serve_local_docs_preview.build_preview_root(docs_root, preview_root)
+
+    config = yaml.safe_load((preview_root / "docs.yml").read_text(encoding="utf-8"))
+    assert "global-theme" not in config
+    assert config["colors"] == serve_local_docs_preview.LOCAL_THEME_CONFIG["colors"]
+    assert config["css"] == ["./styles/base.css", "./styles/local-preview.css"]
+    assert (preview_root / "versions/latest/pages/index.mdx").read_text(encoding="utf-8") == "# Initial\n"
+    assert (preview_root / "components/Authors").read_text(encoding="utf-8") == ("export const Authors = 'initial';\n")
+    assert all(not path.is_symlink() for path in preview_root.rglob("*"))
+    assert all(path.resolve().is_relative_to(preview_root.resolve()) for path in preview_root.rglob("*"))
+
+
+def test_sync_preview_root_updates_adds_and_removes_files(docs_root: Path, tmp_path: Path) -> None:
+    preview_root = tmp_path / "preview"
+    preview_root.mkdir()
+    state = serve_local_docs_preview.build_preview_root(docs_root, preview_root)
+    page = docs_root / "versions/latest/pages/index.mdx"
+    replacement = page.with_suffix(".tmp")
+    replacement.write_text("# Updated\n", encoding="utf-8")
+    replacement.replace(page)
+    added_page = docs_root / "versions/latest/pages/added.mdx"
+    added_page.write_text("# Added\n", encoding="utf-8")
+    (docs_root / "styles/base.css").unlink()
+
+    serve_local_docs_preview.sync_preview_root(docs_root, preview_root, state)
+
+    assert (preview_root / "versions/latest/pages/index.mdx").read_text(encoding="utf-8") == "# Updated\n"
+    assert (preview_root / "versions/latest/pages/added.mdx").read_text(encoding="utf-8") == "# Added\n"
+    assert not (preview_root / "styles/base.css").exists()
+
+
+def test_sync_preview_root_regenerates_docs_config(docs_root: Path, tmp_path: Path) -> None:
+    preview_root = tmp_path / "preview"
+    preview_root.mkdir()
+    state = serve_local_docs_preview.build_preview_root(docs_root, preview_root)
+    config = yaml.safe_load((docs_root / "docs.yml").read_text(encoding="utf-8"))
+    config["title"] = "Updated title"
+    config["global-theme"] = "replacement-theme"
+    (docs_root / "docs.yml").write_text(yaml.safe_dump(config, sort_keys=False), encoding="utf-8")
+
+    serve_local_docs_preview.sync_preview_root(docs_root, preview_root, state)
+
+    preview_config = yaml.safe_load((preview_root / "docs.yml").read_text(encoding="utf-8"))
+    assert preview_config["title"] == "Updated title"
+    assert "global-theme" not in preview_config
+    assert preview_config["colors"] == serve_local_docs_preview.LOCAL_THEME_CONFIG["colors"]
+
+
+def test_sync_preview_root_updates_and_removes_component_alias(docs_root: Path, tmp_path: Path) -> None:
+    preview_root = tmp_path / "preview"
+    preview_root.mkdir()
+    state = serve_local_docs_preview.build_preview_root(docs_root, preview_root)
+    component = docs_root / "components/Authors.tsx"
+    component.write_text("export const Authors = 'updated';\n", encoding="utf-8")
+
+    state = serve_local_docs_preview.sync_preview_root(docs_root, preview_root, state)
+
+    assert (preview_root / "components/Authors.tsx").read_text(encoding="utf-8") == (
+        "export const Authors = 'updated';\n"
+    )
+    assert (preview_root / "components/Authors").read_text(encoding="utf-8") == ("export const Authors = 'updated';\n")
+    component.unlink()
+
+    serve_local_docs_preview.sync_preview_root(docs_root, preview_root, state)
+
+    assert not (preview_root / "components/Authors.tsx").exists()
+    assert not (preview_root / "components/Authors").exists()
+
+
+def test_run_command_synchronizes_until_child_exits(tmp_path: Path) -> None:
+    process = MagicMock()
+    process.wait.side_effect = [subprocess.TimeoutExpired(["fern"], 0.25), 0]
+    initial_state = {Path("docs.yml"): (1, 1, 1)}
+    next_state = {Path("docs.yml"): (2, 1, 1)}
+
+    with (
+        patch.object(serve_local_docs_preview.subprocess, "Popen", return_value=process),
+        patch.object(serve_local_docs_preview, "sync_preview_root", return_value=next_state) as sync,
+    ):
+        result = serve_local_docs_preview.run_command(["fern"], tmp_path, tmp_path, initial_state)
+
+    assert result == 0
+    sync.assert_called_once_with(tmp_path, tmp_path, initial_state)
+
+
+def test_run_command_stops_child_when_synchronization_fails(tmp_path: Path) -> None:
+    process = MagicMock()
+    process.wait.side_effect = [subprocess.TimeoutExpired(["fern"], 0.25), 0]
+
+    with (
+        patch.object(serve_local_docs_preview.subprocess, "Popen", return_value=process),
+        patch.object(serve_local_docs_preview, "sync_preview_root", side_effect=OSError("sync failed")),
+        pytest.raises(OSError, match="sync failed"),
+    ):
+        serve_local_docs_preview.run_command(["fern"], tmp_path, tmp_path, {})
+
+    process.send_signal.assert_called_once_with(serve_local_docs_preview.signal.SIGINT)
diff --git a/plans/fern-live-reload/local-preview-live-reload.md b/plans/fern-live-reload/local-preview-live-reload.md
new file mode 100644
index 000000000..88a47c2f7
--- /dev/null
+++ b/plans/fern-live-reload/local-preview-live-reload.md
@@ -0,0 +1,71 @@
+# Restore Fern fallback live reload
+
+## Context
+
+The unauthenticated Fern fallback added in PR #768 builds a temporary preview
+root with local NVIDIA-style theme settings. Its authored content points back to
+the repository through symlinks. Fern watches the temporary root, so edits made
+under the real `fern/` directory do not produce reload events in the watched
+tree.
+
+Serving the real tree without a theme is not an acceptable fallback. Fern may
+render it differently across CLI releases, and it does not guarantee a close
+match to the published NVIDIA theme.
+
+## Goal
+
+Keep the deterministic local NVIDIA-style fallback while making edits under
+`fern/` reliably trigger Fern live reload.
+
+## Design
+
+Materialize the fallback as real files in the temporary preview root, then poll
+the source tree for metadata changes and mirror only changed paths while the
+Fern child process is running.
+
+- Keep the authenticated path in `Makefile` unchanged.
+- Keep the existing local theme values and `styles/local-preview.css` unchanged.
+- Copy the initial `fern/` tree into the temporary root instead of creating
+  symlinks to the source tree. The current tree is about 19 MB.
+- Track source files by relative path, type, modification time, inode, and size.
+  Poll every 250 ms without adding a file-watching dependency.
+- Copy additions and changes into the temporary root and remove deleted paths.
+  Fern observes those writes inside its watched tree and reloads normally.
+- Regenerate the transformed `docs.yml` whenever the source `docs.yml` changes.
+  Continue removing `global-theme` and applying the deterministic local theme.
+- Preserve extensionless component aliases, but materialize them inside the
+  temporary tree instead of linking them to source files.
+- Retry files that disappear during an editor save on the next pass. Stop the
+  child and exit nonzero for other synchronization failures rather than
+  continuing with a stale preview.
+
+This avoids mutating the working tree, keeps source files editable at their
+normal paths, and works without Fern support for an alternate config file.
+
+## Tasks
+
+- [x] Add focused tests under `fern/scripts/tests/` for the preview wrapper.
+  Cover initial materialization, page edits, file additions and deletions,
+  `docs.yml` regeneration, and component alias updates. Assert that preview
+  files do not resolve outside the temporary root.
+- [x] Update `fern/scripts/serve-local-docs-preview.py` to build a real preview
+  tree and expose one synchronization pass that compares source snapshots and
+  applies changes. Handle files disappearing during editor atomic-save
+  sequences by retrying on the next pass.
+- [x] Change child-process orchestration to synchronize every 250 ms until Fern
+  exits. Preserve interrupt forwarding and ensure synchronization errors stop
+  the child cleanly.
+- [x] Update `fern/README.md` troubleshooting notes to state that the fallback
+  is deterministic and supports live reload without Fern theme access.
+- [x] Validate with:
+  - `.venv/bin/pytest fern/scripts/tests/test_serve_local_docs_preview.py`
+  - `.venv/bin/ruff check --fix .`
+  - `.venv/bin/ruff format .`
+  - `make check-fern-docs`
+  - `make serve-fern-docs-local-theme`, followed by editing an MDX page, a TSX
+    component, and `docs.yml` and confirming each change reloads in the browser
+
+## Open Questions
+
+None. The polling interval and full initial copy are intentionally simple for a
+small local-only documentation tree.

From def57c883f48e8c86190d56620a7aa9318abc928 Mon Sep 17 00:00:00 2001
From: Andre Manoel <amanoel@nvidia.com>
Date: Mon, 6 Jul 2026 18:51:03 -0300
Subject: [PATCH 2/4] fix: handle Fern preview copy races

---
 fern/scripts/serve-local-docs-preview.py      |  5 ++++-
 .../tests/test_serve_local_docs_preview.py    | 21 +++++++++++++++++++
 .../local-preview-live-reload.md              |  2 ++
 3 files changed, 27 insertions(+), 1 deletion(-)
 rename plans/{fern-live-reload => 788}/local-preview-live-reload.md (98%)

diff --git a/fern/scripts/serve-local-docs-preview.py b/fern/scripts/serve-local-docs-preview.py
index 077fa2da8..41b5fc4fb 100644
--- a/fern/scripts/serve-local-docs-preview.py
+++ b/fern/scripts/serve-local-docs-preview.py
@@ -176,7 +176,10 @@ def sync_preview_root(root: Path, preview_root: Path, previous_state: SourceStat
             failed_paths.add(source)
 
     for relative_path in failed_paths:
-        current_state.pop(relative_path, None)
+        if relative_path in previous_state:
+            current_state[relative_path] = previous_state[relative_path]
+        else:
+            current_state.pop(relative_path, None)
     return current_state
 
 
diff --git a/fern/scripts/tests/test_serve_local_docs_preview.py b/fern/scripts/tests/test_serve_local_docs_preview.py
index 5f0c8a6f7..61f746423 100644
--- a/fern/scripts/tests/test_serve_local_docs_preview.py
+++ b/fern/scripts/tests/test_serve_local_docs_preview.py
@@ -77,6 +77,27 @@ def test_sync_preview_root_updates_adds_and_removes_files(docs_root: Path, tmp_p
     assert not (preview_root / "styles/base.css").exists()
 
 
+def test_sync_preview_root_removes_file_deleted_during_copy(docs_root: Path, tmp_path: Path) -> None:
+    preview_root = tmp_path / "preview"
+    preview_root.mkdir()
+    state = serve_local_docs_preview.build_preview_root(docs_root, preview_root)
+    page = docs_root / "versions/latest/pages/index.mdx"
+    page.write_text("# Updated\n", encoding="utf-8")
+    relative_path = page.relative_to(docs_root)
+
+    def delete_source(*args: object, **kwargs: object) -> None:
+        page.unlink()
+        raise FileNotFoundError
+
+    with patch.object(serve_local_docs_preview, "copy_preview_file", side_effect=delete_source):
+        state = serve_local_docs_preview.sync_preview_root(docs_root, preview_root, state)
+
+    assert relative_path in state
+    state = serve_local_docs_preview.sync_preview_root(docs_root, preview_root, state)
+    assert relative_path not in state
+    assert not (preview_root / relative_path).exists()
+
+
 def test_sync_preview_root_regenerates_docs_config(docs_root: Path, tmp_path: Path) -> None:
     preview_root = tmp_path / "preview"
     preview_root.mkdir()
diff --git a/plans/fern-live-reload/local-preview-live-reload.md b/plans/788/local-preview-live-reload.md
similarity index 98%
rename from plans/fern-live-reload/local-preview-live-reload.md
rename to plans/788/local-preview-live-reload.md
index 88a47c2f7..e687cdecd 100644
--- a/plans/fern-live-reload/local-preview-live-reload.md
+++ b/plans/788/local-preview-live-reload.md
@@ -1,5 +1,7 @@
 # Restore Fern fallback live reload
 
+Tracking: PR #788 (no linked issue).
+
 ## Context
 
 The unauthenticated Fern fallback added in PR #768 builds a temporary preview

From 68655393032a20ca1239a7711ba80da20c34d176 Mon Sep 17 00:00:00 2001
From: Andre Manoel <amanoel@nvidia.com>
Date: Tue, 7 Jul 2026 17:49:55 -0300
Subject: [PATCH 3/4] fix: handle transient Fern preview edits

---
 fern/scripts/serve-local-docs-preview.py      | 22 +++++---
 .../tests/test_serve_local_docs_preview.py    | 54 +++++++++++++++++++
 plans/788/local-preview-live-reload.md        | 10 ++--
 3 files changed, 73 insertions(+), 13 deletions(-)

diff --git a/fern/scripts/serve-local-docs-preview.py b/fern/scripts/serve-local-docs-preview.py
index 41b5fc4fb..fdb151794 100644
--- a/fern/scripts/serve-local-docs-preview.py
+++ b/fern/scripts/serve-local-docs-preview.py
@@ -63,6 +63,8 @@ def parse_args() -> argparse.Namespace:
 
 def write_local_docs_config(root: Path, preview_root: Path) -> None:
     config = yaml.safe_load((root / "docs.yml").read_text(encoding="utf-8"))
+    if not isinstance(config, dict):
+        raise yaml.YAMLError("docs.yml must contain a mapping")
     config.pop("global-theme", None)
 
     for key, value in LOCAL_THEME_CONFIG.items():
@@ -102,11 +104,11 @@ def snapshot_source(root: Path) -> SourceState:
 
 def component_aliases(state: SourceState) -> dict[Path, Path]:
     aliases = {}
-    for source in state:
+    for source in sorted(state):
         if source.parts[:1] != ("components",) or source.suffix not in COMPONENT_EXTENSIONS:
             continue
         alias = source.with_suffix("")
-        if alias not in state:
+        if alias not in state and alias not in aliases:
             aliases[alias] = source
     return aliases
 
@@ -162,18 +164,22 @@ def sync_preview_root(root: Path, preview_root: Path, previous_state: SourceStat
                 write_local_docs_config(root, preview_root)
             else:
                 copy_preview_file(root, preview_root, relative_path)
-        except FileNotFoundError:
+        except (OSError, yaml.YAMLError):
             failed_paths.add(relative_path)
 
     changed_aliases = {
-        alias for alias, source in current_aliases.items() if alias not in previous_aliases or source in changed_paths
+        alias
+        for alias, source in current_aliases.items()
+        if previous_aliases.get(alias) != source or source in changed_paths
     }
     for alias in sorted(changed_aliases):
         source = current_aliases[alias]
         try:
             copy_preview_file(root, preview_root, source, alias)
-        except FileNotFoundError:
+        except OSError:
             failed_paths.add(source)
+            if alias in previous_aliases:
+                failed_paths.add(previous_aliases[alias])
 
     for relative_path in failed_paths:
         if relative_path in previous_state:
@@ -183,14 +189,14 @@ def sync_preview_root(root: Path, preview_root: Path, previous_state: SourceStat
     return current_state
 
 
-def run_command(command: list[str], cwd: Path, root: Path, source_state: SourceState) -> int:
-    process = subprocess.Popen(command, cwd=cwd)
+def run_command(command: list[str], preview_root: Path, root: Path, source_state: SourceState) -> int:
+    process = subprocess.Popen(command, cwd=preview_root)
     try:
         while True:
             try:
                 return process.wait(timeout=POLL_INTERVAL_SECONDS)
             except subprocess.TimeoutExpired:
-                source_state = sync_preview_root(root, cwd, source_state)
+                source_state = sync_preview_root(root, preview_root, source_state)
     except KeyboardInterrupt:
         process.send_signal(signal.SIGINT)
         return process.wait()
diff --git a/fern/scripts/tests/test_serve_local_docs_preview.py b/fern/scripts/tests/test_serve_local_docs_preview.py
index 61f746423..6dfafae45 100644
--- a/fern/scripts/tests/test_serve_local_docs_preview.py
+++ b/fern/scripts/tests/test_serve_local_docs_preview.py
@@ -58,6 +58,20 @@ def test_build_preview_root_materializes_local_theme(docs_root: Path, tmp_path:
     assert all(path.resolve().is_relative_to(preview_root.resolve()) for path in preview_root.rglob("*"))
 
 
+def test_build_preview_root_uses_first_component_extension(docs_root: Path, tmp_path: Path) -> None:
+    preview_root = tmp_path / "preview"
+    preview_root.mkdir()
+    component = docs_root / "components/Authors.ts"
+    component.write_text("export const Authors = 'ts';\n", encoding="utf-8")
+
+    state = serve_local_docs_preview.build_preview_root(docs_root, preview_root)
+
+    assert (preview_root / "components/Authors").read_text(encoding="utf-8") == "export const Authors = 'ts';\n"
+    component.unlink()
+    serve_local_docs_preview.sync_preview_root(docs_root, preview_root, state)
+    assert (preview_root / "components/Authors").read_text(encoding="utf-8") == "export const Authors = 'initial';\n"
+
+
 def test_sync_preview_root_updates_adds_and_removes_files(docs_root: Path, tmp_path: Path) -> None:
     preview_root = tmp_path / "preview"
     preview_root.mkdir()
@@ -77,6 +91,23 @@ def test_sync_preview_root_updates_adds_and_removes_files(docs_root: Path, tmp_p
     assert not (preview_root / "styles/base.css").exists()
 
 
+def test_sync_preview_root_retries_transient_copy_error(docs_root: Path, tmp_path: Path) -> None:
+    preview_root = tmp_path / "preview"
+    preview_root.mkdir()
+    state = serve_local_docs_preview.build_preview_root(docs_root, preview_root)
+    page = docs_root / "versions/latest/pages/added.mdx"
+    page.write_text("# Added\n", encoding="utf-8")
+    relative_path = page.relative_to(docs_root)
+
+    with patch.object(serve_local_docs_preview, "copy_preview_file", side_effect=PermissionError):
+        state = serve_local_docs_preview.sync_preview_root(docs_root, preview_root, state)
+
+    assert relative_path not in state
+    assert not (preview_root / relative_path).exists()
+    state = serve_local_docs_preview.sync_preview_root(docs_root, preview_root, state)
+    assert (preview_root / relative_path).read_text(encoding="utf-8") == "# Added\n"
+
+
 def test_sync_preview_root_removes_file_deleted_during_copy(docs_root: Path, tmp_path: Path) -> None:
     preview_root = tmp_path / "preview"
     preview_root.mkdir()
@@ -115,6 +146,29 @@ def test_sync_preview_root_regenerates_docs_config(docs_root: Path, tmp_path: Pa
     assert preview_config["colors"] == serve_local_docs_preview.LOCAL_THEME_CONFIG["colors"]
 
 
+@pytest.mark.parametrize("invalid_config", ["", "title: ["])
+def test_sync_preview_root_retries_invalid_docs_config(
+    docs_root: Path,
+    tmp_path: Path,
+    invalid_config: str,
+) -> None:
+    preview_root = tmp_path / "preview"
+    preview_root.mkdir()
+    state = serve_local_docs_preview.build_preview_root(docs_root, preview_root)
+    previous_docs_state = state[serve_local_docs_preview.DOCS_CONFIG_PATH]
+    docs_config = docs_root / "docs.yml"
+    docs_config.write_text(invalid_config, encoding="utf-8")
+
+    state = serve_local_docs_preview.sync_preview_root(docs_root, preview_root, state)
+
+    assert state[serve_local_docs_preview.DOCS_CONFIG_PATH] == previous_docs_state
+    assert yaml.safe_load((preview_root / "docs.yml").read_text(encoding="utf-8"))["title"] == "Data Designer"
+    docs_config.write_text("title: Updated title\n", encoding="utf-8")
+    state = serve_local_docs_preview.sync_preview_root(docs_root, preview_root, state)
+    assert state[serve_local_docs_preview.DOCS_CONFIG_PATH] != previous_docs_state
+    assert yaml.safe_load((preview_root / "docs.yml").read_text(encoding="utf-8"))["title"] == "Updated title"
+
+
 def test_sync_preview_root_updates_and_removes_component_alias(docs_root: Path, tmp_path: Path) -> None:
     preview_root = tmp_path / "preview"
     preview_root.mkdir()
diff --git a/plans/788/local-preview-live-reload.md b/plans/788/local-preview-live-reload.md
index e687cdecd..827c110b4 100644
--- a/plans/788/local-preview-live-reload.md
+++ b/plans/788/local-preview-live-reload.md
@@ -37,9 +37,9 @@ Fern child process is running.
   Continue removing `global-theme` and applying the deterministic local theme.
 - Preserve extensionless component aliases, but materialize them inside the
   temporary tree instead of linking them to source files.
-- Retry files that disappear during an editor save on the next pass. Stop the
-  child and exit nonzero for other synchronization failures rather than
-  continuing with a stale preview.
+- Retry transient file access failures and invalid `docs.yml` edits on the next
+  pass. Stop the child and exit nonzero for unexpected synchronization failures
+  rather than continuing with a stale preview.
 
 This avoids mutating the working tree, keeps source files editable at their
 normal paths, and works without Fern support for an alternate config file.
@@ -52,8 +52,8 @@ normal paths, and works without Fern support for an alternate config file.
   files do not resolve outside the temporary root.
 - [x] Update `fern/scripts/serve-local-docs-preview.py` to build a real preview
   tree and expose one synchronization pass that compares source snapshots and
-  applies changes. Handle files disappearing during editor atomic-save
-  sequences by retrying on the next pass.
+  applies changes. Handle transient copy failures and invalid configuration
+  during editor saves by retrying on the next pass.
 - [x] Change child-process orchestration to synchronize every 250 ms until Fern
   exits. Preserve interrupt forwarding and ensure synchronization errors stop
   the child cleanly.

From 2e005dc00c71b362f47dcd7e6104eaaa0deed5aa Mon Sep 17 00:00:00 2001
From: Andre Manoel <amanoel@nvidia.com>
Date: Wed, 8 Jul 2026 09:56:38 -0300
Subject: [PATCH 4/4] fix: tolerate unreadable files in Fern preview snapshot

---
 fern/scripts/serve-local-docs-preview.py         |  4 ++--
 .../tests/test_serve_local_docs_preview.py       | 16 ++++++++++++++++
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/fern/scripts/serve-local-docs-preview.py b/fern/scripts/serve-local-docs-preview.py
index fdb151794..5a79a57f8 100644
--- a/fern/scripts/serve-local-docs-preview.py
+++ b/fern/scripts/serve-local-docs-preview.py
@@ -96,7 +96,7 @@ def snapshot_source(root: Path) -> SourceState:
             if not source.is_file():
                 continue
             stat = source.stat()
-        except FileNotFoundError:
+        except OSError:
             continue
         state[source.relative_to(root)] = (stat.st_mtime_ns, stat.st_ino, stat.st_size)
     return state
@@ -114,7 +114,7 @@ def component_aliases(state: SourceState) -> dict[Path, Path]:
 
 
 def copy_preview_file(root: Path, preview_root: Path, source: Path, target: Path | None = None) -> None:
-    target = preview_root / (target or source)
+    target = preview_root / (source if target is None else target)
     target.parent.mkdir(parents=True, exist_ok=True)
     shutil.copy2(root / source, target)
 
diff --git a/fern/scripts/tests/test_serve_local_docs_preview.py b/fern/scripts/tests/test_serve_local_docs_preview.py
index 6dfafae45..1978bb74c 100644
--- a/fern/scripts/tests/test_serve_local_docs_preview.py
+++ b/fern/scripts/tests/test_serve_local_docs_preview.py
@@ -91,6 +91,22 @@ def test_sync_preview_root_updates_adds_and_removes_files(docs_root: Path, tmp_p
     assert not (preview_root / "styles/base.css").exists()
 
 
+def test_snapshot_source_skips_unreadable_file(docs_root: Path) -> None:
+    page = docs_root / "versions/latest/pages/index.mdx"
+    original_stat = Path.stat
+
+    def deny_page_stat(self: Path, **kwargs: object) -> object:
+        if self == page:
+            raise PermissionError
+        return original_stat(self, **kwargs)
+
+    with patch.object(Path, "stat", deny_page_stat):
+        state = serve_local_docs_preview.snapshot_source(docs_root)
+
+    assert page.relative_to(docs_root) not in state
+    assert Path("docs.yml") in state
+
+
 def test_sync_preview_root_retries_transient_copy_error(docs_root: Path, tmp_path: Path) -> None:
     preview_root = tmp_path / "preview"
     preview_root.mkdir()